Time evolution¶
Time-dependent PDEs such as the heat, wave or Schrödinger equation can be
solved with the method of lines: discretize space on a grid and integrate
the resulting system of ODEs in time. evolve does this with
scipy.integrate.solve_ivp(), while letting you write the right-hand
side in terms of grid-shaped arrays.
from numgrids import *
import numpy as np
A first example: the heat equation¶
\(\partial_t u = \kappa\, \partial_x^2 u\) on \([0, 1]\) with \(u = 0\) at both ends:
grid = Grid(x=chebyshev(40, 0, 1))
x = grid.coords
kappa = 0.1
result = evolve(
grid,
lambda t, u: kappa * grid.laplacian(u), # right-hand side
np.sin(np.pi * x), # initial condition
t_span=(0, 1),
t_eval=np.linspace(0, 1, 11),
bcs=0,
method="BDF", # implicit: diffusion is stiff
)
result.t # the 11 time points
result.u.shape # (11, 40)
result.final # solution at t = 1
For linear problems you can pass an Operator instead of a function. Implicit methods then use its sparse matrix as the Jacobian, which makes them fast:
result = evolve(grid, kappa * grid.laplacian_operator(), np.sin(np.pi * x),
(0, 1), bcs=0, method="BDF")
Boundary conditions¶
bcs accepts the compact specifications of
Dirichlet, Neumann and Robin conditions. The conditions hold at every
instant: the boundary values are not evolved themselves but computed from
the interior values so that the conditions are satisfied. The initial state
is adjusted accordingly. For Dirichlet conditions this simply means the
prescribed values.
# Temperature 1 on the left, 3 on the right; relaxes to a linear profile
result = evolve(grid, grid.laplacian_operator(), np.zeros(grid.shape), (0, 5),
bcs={"x_low": 1, "x_high": 3}, method="Radau")
An insulated rod (\(\partial u / \partial n = 0\) at both ends) keeps its total heat, and the temperature levels out:
u0 = 1 + np.cos(np.pi * x)
result = evolve(grid, grid.laplacian_operator(), u0, (0, 2), bcs=Neumann(0), method="BDF")
grid.integrate(result.final) # 1.0, as at t = 0
Newton’s law of cooling at a surface, \(-k\,\partial u / \partial n = h\,(u - u_\infty)\), is a Robin condition \(h u + k\,\partial u / \partial n = h u_\infty\):
h, k, u_inf = 2.0, 1.0, 0.0
result = evolve(grid, grid.laplacian_operator(), np.ones(grid.shape), (0, 1),
bcs={"x_low": Neumann(0), "x_high": Robin(h, k, u_inf)}, method="BDF")
Boundary values that change in time¶
Wrap a function of time in TimeDependent to prescribe boundary values
that change in time. It works for Dirichlet, Neumann and Robin conditions:
# The left end is heated periodically, the right end is insulated
result = evolve(grid, grid.laplacian_operator(), np.zeros(grid.shape), (0, 10),
bcs={"x_low": TimeDependent(lambda t: np.sin(t)), "x_high": Neumann(0)},
method="BDF")
# A prescribed heat flux that is switched off at t = 1
bcs = {"x_low": 0, "x_high": Neumann(TimeDependent(lambda t: 1.0 if t < 1 else 0.0))}
On faces of two- and three-dimensional grids, the function of time may return a function of the face coordinates (or an array), just like time-independent boundary values:
g = TimeDependent(lambda t: lambda c: np.exp(-t) * np.sin(np.pi * c[1]))
Source terms¶
source= adds a source term \(s\) to the right-hand side,
\(\partial_t u = F(t, u) + s\). It is an array of grid shape or a function of
time returning one. With an operator as right-hand side the problem stays
linear, and implicit methods keep the exact Jacobian:
grid = Grid(x=chebyshev(40, 0, 1))
x = grid.coords
heating = lambda t: np.exp(-50 * (x - 0.5)**2) * np.sin(t)**2
result = evolve(grid, 0.1 * grid.laplacian_operator(), np.zeros(grid.shape), (0, 10),
bcs=0, method="BDF", source=heating)
Coupled fields: the wave equation¶
Pass a tuple of initial fields to integrate a system; the right-hand side then receives and returns one array per field. The wave equation \(\partial_t^2 u = c^2 \nabla^2 u\) becomes \(\partial_t u = v\), \(\partial_t v = c^2 \nabla^2 u\), here on a circular drum (a full disk with a radial axis):
grid = PolarGrid(radial(24, 1.0), periodic(32))
X, Y = grid.cartesian_coords
u0 = np.exp(-20 * ((X - 0.3)**2 + Y**2))
result = evolve(
grid,
lambda t, u, v: (v, grid.laplacian(u)),
(u0, np.zeros_like(u0)),
t_span=(0, 2),
t_eval=np.linspace(0, 2, 50),
bcs=0,
)
u, v = result.u # each of shape (50, 24, 32)
grid.plot(u[-1])
Linear systems can also be written as a nested list of operator blocks,
rhs[i][j] acting on field j in the equation of field i. A block is
an operator, an array of grid shape (multiplication), a number, or None
for zero. Implicit methods then use the exact Jacobian of the system, and
the exponential integrator
becomes available:
L = grid.laplacian_operator()
result = evolve(grid, [[None, 1], [L, None]], # u_t = v, v_t = L u
(u0, np.zeros_like(u0)), (0, 2), bcs=0)
For systems, a single boundary condition specification applies to the
first field, and the other fields are held fixed on the same boundary
points. That is what \(\partial_t u = v\) formulations need. To give each
field its own conditions, pass a tuple with one specification per field
(None for none). Here is a reaction-diffusion system with no-flux
boundaries for both species:
grid = Grid(x=chebyshev(40, 0, 10))
x = grid.coords
result = evolve(
grid,
lambda t, a, b: (grid.laplacian(a) + a - a * b, 0.5 * grid.laplacian(b) + a * b - b),
(1 + 0.5 * np.cos(np.pi * x / 10), np.ones(grid.shape)),
t_span=(0, 5),
bcs=(Neumann(0), Neumann(0)),
)
Complex fields: the Schrödinger equation¶
Complex initial states are supported by the explicit methods (RK45,
DOP853, …):
grid = Grid(x=periodic(128, -20, 20))
x = grid.coords
psi0 = np.exp(-x**2 + 2j * x)
result = evolve(grid, lambda t, psi: 0.5j * grid.diff(psi, 2), psi0, (0, 2),
t_eval=[0, 1, 2], rtol=1e-8)
Linear problems without time stepping error¶
For linear problems with constant boundary values and sources, the
solution is known in closed form, \(u(t) = e^{tL} u_0\) (plus the
contribution of sources and boundary values). method="expm" evaluates it
with matrix exponentials, directly at the requested times:
grid = Grid(x=chebyshev(40, 0, 1))
x = grid.coords
result = evolve(grid, 0.1 * grid.laplacian_operator(), np.sin(np.pi * x), (0, 5),
t_eval=[0, 0.1, 1, 5], bcs=0, method="expm")
There is no time step and hence no time stepping error, however stiff the problem and however long the time interval. The right-hand side must be an operator (or a list of operator blocks for systems).
This is the method of choice for the Schrödinger equation \(i\,\partial_t \psi = H \psi\): the fields are complex, the operator is stiff, and the norm is conserved to round-off, also over long times:
grid = Grid(x=chebyshev(120, -15, 15))
x = grid.coords
H = -0.5 * grid.diff_operator(2) + 0.5 * x**2 # harmonic oscillator
psi0 = np.pi**-0.25 * np.exp(-(x - 2)**2 / 2) # displaced ground state
result = evolve(grid, -1j * H, psi0, (0, 2 * np.pi), t_eval=np.linspace(0, 2 * np.pi, 9),
bcs=0, method="expm")
grid.norm(result.final) # 1.0
abs(grid.inner(psi0, result.final)) # 1.0: back after one period
Up to 2000 unknowns the matrix exponential is computed once per distinct
time step (equally spaced output times need only one), which also makes
long series of outputs cheap. Larger problems use
scipy.sparse.linalg.expm_multiply(), whose cost grows with the
stiffness of the operator.
Stiff nonlinear problems¶
Many nonlinear PDEs are semilinear,
with a linear part \(L\) that contains the highest derivatives and is
therefore stiff, and a nonlinear part \(N\) that is not: the Korteweg-de
Vries, nonlinear Schrödinger, Kuramoto-Sivashinsky, Allen-Cahn and
Swift-Hohenberg equations, and reaction-diffusion systems. Explicit
methods need tiny time steps for \(L\), and implicit methods have to solve
nonlinear systems in every step. If you pass the linear part separately,
as linear=, evolve can treat the two parts differently. The right-hand
side rhs is then only the nonlinear part:
# Korteweg-de Vries equation u_t + 6 u u_x + u_xxx = 0
grid = Grid(x=periodic(256, -20, 20))
x = grid.coords
c = 4.0
soliton = lambda t: c / 2 / np.cosh(np.sqrt(c) / 2 * (x + 10 - c * t))**2
D = grid.diff_operator()
result = evolve(
grid,
lambda t, u: -3 * D(u**2), # nonlinear part: -6 u u_x
soliton(0),
t_span=(0, 5),
t_eval=np.linspace(0, 5, 11),
linear=-grid.diff_operator(3), # stiff linear part: -u_xxx
method="ETDRK4",
dt=0.005,
)
abs(result.final - soliton(5)).max() # 7e-5: the soliton has moved by 20
The methods integrate with a fixed time step dt:
Method |
Order |
Linear part |
Cost per step |
|---|---|---|---|
|
4 |
exact |
4 evaluations of \(N\) |
|
2 |
exact |
2 evaluations of \(N\) |
|
1 |
exact |
1 evaluation of \(N\) |
|
2 |
implicit (L-stable) |
2 evaluations of \(N\), 2 linear solves |
The exponential time differencing (ETD) methods integrate the linear
part exactly, with the matrix exponential \(e^{hL}\) and related functions,
and the nonlinear part with an explicit Runge-Kutta scheme. The time step
is limited by the nonlinear part only, not by the stiffness of \(L\).
"ETDRK4" is the method of choice in most cases. "IMEX2" is an
implicit-explicit Runge-Kutta scheme: it only solves linear systems with
the matrix \(1 - \gamma h L\), which makes it suitable for large problems on
grids with boundaries (see below).
There is no error control: choose dt by comparing with a run with half
the step. Every interval between two output times is divided into equal
steps that are not longer than dt, so the times in t_eval are hit
exactly; without t_eval the result holds the start and end time. If the
solution blows up, result.success is False, result.message tells
where, and the result ends with the last output time before that.
Complex fields work as well. For the nonlinear Schrödinger equation \(i\,\partial_t \psi + \tfrac12 \partial_x^2 \psi + |\psi|^2 \psi = 0\) with the soliton \(\psi = \operatorname{sech}(x)\, e^{it/2}\):
grid = Grid(x=periodic(256, -20, 20))
x = grid.coords
result = evolve(grid, lambda t, psi: 1j * abs(psi)**2 * psi, 1 / np.cosh(x), (0, 10),
linear=0.5j * grid.diff_operator(2), method="ETDRK4", dt=0.05)
abs(result.final - np.exp(5j) / np.cosh(x)).max() # 3e-6
grid.norm(result.final)**2 # 2.0, as at t = 0
Periodic grids: time stepping in Fourier space¶
On a grid that is periodic along all axes, a linear part with constant
coefficients is diagonal in Fourier space. evolve detects this and does
the time stepping on the Fourier coefficients, with fast Fourier
transforms and no matrices at all. Two-dimensional problems on large grids
are cheap this way. For systems, linear is a nested list of blocks like
a linear right-hand side. Here is the
Gray-Scott reaction-diffusion system, in which a small seed of the species
\(v\) grows into a labyrinth of stripes:
grid = Grid(x=periodic(64, 0, 1.25), y=periodic(64, 0, 1.25))
X, Y = grid.meshed_coords
Lap = grid.laplacian_operator()
F, k = 0.037, 0.06
seed = np.exp(-((X - 0.6)**2 + (Y - 0.65)**2) / 0.005)
result = evolve(
grid,
lambda t, u, v: (-u * v**2 + F * (1 - u), u * v**2 - (F + k) * v),
(1 - 0.5 * seed, 0.25 * seed),
t_span=(0, 2000),
linear=[[2e-5 * Lap, None], [None, 1e-5 * Lap]],
method="ETDRK4",
dt=2.0,
)
u, v = result.final
The blocks may also couple the fields, e.g. [[None, 1], [L, None]] for
a nonlinear wave equation \(\partial_t^2 u = \nabla^2 u + f(u)\); each
Fourier mode then has a small matrix instead of a number.
Operators with mixed derivatives, such as \(\nabla^4 = \partial_x^4 + 2\,\partial_x^2 \partial_y^2 + \partial_y^4\), have dense matrices in two dimensions: \(N^4\) entries on an \(N \times N\) grid. On periodic grids you can avoid the matrix and pass the Fourier symbol of the linear part instead, a function of the meshed wave numbers: the factor by which the operator multiplies \(e^{i (k_x x + k_y y)}\) (so \(\partial_x\) becomes \(i k_x\) and \(\nabla^2\) becomes \(-k_x^2 - k_y^2\)). For the Swift-Hohenberg equation \(\partial_t u = r u - (1 + \nabla^2)^2 u - u^3\), which forms stripes with the wave number 1:
grid = Grid(x=periodic(128, 0, 32 * np.pi), y=periodic(128, 0, 32 * np.pi))
u0 = 0.1 * np.random.default_rng(0).standard_normal(grid.shape)
result = evolve(grid, lambda t, u: -u**3, u0, (0, 100),
linear=lambda kx, ky: 0.3 - (1 - kx**2 - ky**2)**2,
method="ETDRK4", dt=0.5)
The eigenvalues of this linear part reach \(-960\), so explicit methods would need steps of about 0.003 here. In a nested list for systems, symbols and operators can be mixed.
Grids with boundaries¶
On other grids, with boundary conditions, or with coefficients that vary in space, the ETD methods compute the functions of the linear part as dense matrices, once per step size (for equally spaced output times: once). Dirichlet, Neumann and Robin conditions work as for the other methods. The Allen-Cahn equation \(\partial_t u = \epsilon\, \partial_x^2 u + u - u^3\) forms plateaus \(u = \pm 1\) that last for a long time:
grid = Grid(x=chebyshev(64, -1, 1))
x = grid.coords
u0 = 0.53 * x + 0.47 * np.sin(-1.5 * np.pi * x)
result = evolve(grid, lambda t, u: u - u**3, u0, (0, 30), t_eval=np.linspace(0, 30, 61),
bcs={"x_low": -1, "x_high": 1},
linear=0.01 * grid.diff_operator(2), method="ETDRK4", dt=0.25)
Constant boundary values and constant sources are part of the linear
problem and are integrated exactly: without a nonlinear part, the ETD
methods reproduce method=”expm”.
Boundary values and sources that change in time are treated like the
nonlinear part; with time-dependent boundary values
the observed order of "ETDRK4" drops from 4 to about 3, while the
second-order methods keep their order.
Dense matrix functions limit the ETD methods to 2500 unknowns on such
grids, and their setup takes about a hundred matrix products (a few
seconds for 1500 unknowns). Larger problems are the domain of "IMEX2",
which solves its linear systems like Operator.solve:
with sparse or dense factorizations, or decoupled into Fourier modes where
the problem allows it (systems of several fields: with dense or sparse LU
factorizations). Here on a disk:
grid = PolarGrid(radial(24, 1.0), periodic(32))
X, Y = grid.cartesian_coords
result = evolve(grid, lambda t, u: u * (1 - u), np.exp(-10 * ((X - 0.3)**2 + Y**2)), (0, 5),
bcs=Neumann(0), linear=0.05 * grid.laplacian_operator(), method="IMEX2", dt=0.02)
Looking at the result¶
result.animate() returns a matplotlib animation of the solution, and
result.to_vtk("run") writes a time series for ParaView; see
Plotting and
Saving and loading.
Options¶
Additional keyword arguments (rtol, atol, max_step, first_step,
…) are passed on to scipy.integrate.solve_ivp(); the raw solver
result is available as result.sol. method="expm" and the fixed-step
methods of the previous section take no further options.