Boundary conditions¶
numgrids provides three boundary condition types – Dirichlet, Neumann, and Robin – that can be applied either directly to array data or to sparse linear systems built from differentiation matrices. This makes it straightforward to set up and solve boundary value problems.
from numgrids import *
import numpy as np
Boundary faces¶
Before applying a boundary condition you need a BoundaryFace, which
identifies one side of the grid boundary. The easiest way to get them is
through grid.faces:
grid = Grid(
create_axis(AxisType.CHEBYSHEV, 30, 0.0, 1.0),
create_axis(AxisType.CHEBYSHEV, 30, 0.0, 1.0),
)
print(grid.faces.keys())
# dict_keys(['0_low', '0_high', '1_low', '1_high'])
The key format is "{axis_index}_{side}", where side is either "low"
(first point along that axis) or "high" (last point). Periodic axes have
no boundary faces and are automatically excluded; so are ends that are not a
boundary, such as the ends at infinity of
unbounded axes, where no condition is imposed.
For named axes, the key
"{name}_{side}" works as well:
grid = Grid(x=chebyshev(30, 0.0, 1.0), y=chebyshev(30, 0.0, 1.0))
grid.faces["x_low"] is grid.faces["0_low"] # True
Each BoundaryFace exposes:
mask– a boolean array of shapegrid.shape,Trueon the faceflat_indices– 1D indices of the face points in the ravelled gridnormal_sign–-1for"low",+1for"high"(outward normal direction)key,shapeandcoords– the face key, the shape of face arrays, and the meshed coordinates restricted to the face
Compact boundary condition specifications¶
Most of the time you do not need to construct DirichletBC objects by
hand. Operator.solve, Operator.eig,
solve_nonlinear, evolve and
apply_bcs(..., grid=grid) accept compact specifications:
grid = Grid(x=chebyshev(30, 0.0, 1.0), y=chebyshev(30, 0.0, 1.0))
L = grid.laplacian_operator()
rhs = np.ones(grid.shape)
u = L.solve(rhs, bcs=0) # u = 0 on all faces
u = L.solve(rhs, bcs=lambda c: c[0] * c[1]) # u = x*y on all faces
u = L.solve(rhs, bcs={
"all": 0, # default for all faces ...
"x_high": 1.0, # ... overridden: u = 1
"y_low": Neumann(0.0), # du/dn = 0
"y_high": Robin(a=1.0, b=0.5, value=0.0), # u + 0.5 du/dn = 0
})
Plain values (numbers, arrays, callables) mean Dirichlet conditions;
Dirichlet, Neumann and Robin are unbound specs that are attached to
the face given by the dictionary key. resolve_bcs(grid, spec) turns any
such specification into a list of bound conditions.
DirichletBC¶
A Dirichlet condition prescribes the function value on a boundary face: \(u = g\).
Applying to arrays¶
The apply() method sets the boundary values in-place:
face = grid.faces["0_low"]
bc = DirichletBC(face, value=0.0)
u = np.ones(grid.shape)
bc.apply(u)
# u is now 0.0 along the x=0 boundary
Applying to a linear system¶
The apply_to_system() method modifies a sparse matrix and right-hand-side
vector. Boundary rows in the matrix are replaced with identity rows, and the
corresponding RHS entries are set to \(g\):
D_xx = Diff(grid, order=2, axis_index=0).as_matrix()
D_yy = Diff(grid, order=2, axis_index=1).as_matrix()
L = D_xx + D_yy # Laplacian matrix
rhs = np.zeros(grid.size)
L, rhs = bc.apply_to_system(L, rhs) # returns modified copies
NeumannBC¶
A Neumann condition prescribes the outward normal derivative: \(\partial u / \partial n = g\).
Applying to arrays¶
The apply() method adjusts the boundary layer using a first-order
finite-difference approximation of the normal derivative:
face = grid.faces["0_high"]
bc = NeumannBC(face, value=1.0)
bc.apply(u)
Applying to a linear system¶
For higher accuracy, use apply_to_system(). It replaces boundary rows with
the differentiation-matrix rows scaled by the outward normal sign:
L, rhs = bc.apply_to_system(L, rhs)
RobinBC¶
A Robin condition is a linear combination of Dirichlet and Neumann: \(a\,u + b\,\partial u / \partial n = g\).
face = grid.faces["1_high"]
bc = RobinBC(face, a=1.0, b=0.5, value=2.0)
Warning
Robin boundary conditions support only apply_to_system(), not apply().
Calling apply() raises NotImplementedError.
L, rhs = bc.apply_to_system(L, rhs)
The coefficients a and b may vary along the face. Like the value, they
can be arrays matching the face or functions of the face coordinates. An
example is Newton’s law of cooling, \(h\,u + k\,\partial u/\partial n = h\,u_\infty\),
at a surface whose conductivity \(k\) depends on the position:
bcs = {"y_high": Robin(2.0, lambda c: 1 + c[0], 0.0)} # k = 1 + x along the face y = y_max
Applying multiple BCs at once¶
The apply_bcs() function takes a list of boundary conditions and applies
them to a linear system in order. For overlapping points (e.g. corners), the
last condition in the list wins:
bcs = [
DirichletBC(grid.faces["0_low"], value=0.0),
DirichletBC(grid.faces["0_high"], value=0.0),
NeumannBC(grid.faces["1_low"], value=0.0),
NeumannBC(grid.faces["1_high"], value=0.0),
]
L, rhs = apply_bcs(bcs, L, rhs)
Callable boundary values¶
All BC types accept a callable for value. The callable receives a tuple of
coordinate arrays restricted to the boundary face and must return an array:
# u = sin(pi * y) on the left boundary
bc = DirichletBC(
grid.faces["0_low"],
value=lambda coords: np.sin(np.pi * coords[1]),
)
Here coords[1] is the y-coordinate array along the face. This is useful
for spatially varying boundary data.
Working with boundary faces¶
Faces also provide operations for post-processing, e.g. fluxes and surface integrals:
X, Y = grid.meshed_coords
f = X**2 * Y
face = grid.faces["x_high"]
face.restrict(f) # values on the face, shape face.shape
face.normal_derivative(f) # outward normal derivative on the face
face.integrate(f) # surface integral
face.flux(*grid.gradient(f)) # outward flux of a vector field
# Gauss's theorem: total outward flux = volume integral of the divergence
sum(face.flux(*grid.gradient(f)) for face in grid.faces.values())
On curvilinear grids, normal_derivative returns the physical derivative
\(\pm(1/h_i)\,\partial f/\partial q_i\) and integrate includes the
surface element (e.g. \(r^2\sin\theta\) on a sphere).
Worked example: solving the Poisson equation¶
Solve \(\nabla^2 u = -2\pi^2 \sin(\pi x)\sin(\pi y)\) on \([0,1]^2\) with \(u = 0\) on all boundaries. The exact solution is \(u(x, y) = \sin(\pi x)\sin(\pi y)\).
from numgrids import *
import numpy as np
from scipy.sparse.linalg import spsolve
# Build grid
grid = Grid(
create_axis(AxisType.CHEBYSHEV, 30, 0.0, 1.0),
create_axis(AxisType.CHEBYSHEV, 30, 0.0, 1.0),
)
X, Y = grid.meshed_coords
# Build Laplacian operator as sparse matrix
D_xx = Diff(grid, order=2, axis_index=0).as_matrix()
D_yy = Diff(grid, order=2, axis_index=1).as_matrix()
L = D_xx + D_yy
# Right-hand side
rhs = (-2 * np.pi**2 * np.sin(np.pi * X) * np.sin(np.pi * Y)).ravel()
# Dirichlet u=0 on all four boundaries
bcs = [DirichletBC(face, value=0.0) for face in grid.faces.values()]
L, rhs = apply_bcs(bcs, L, rhs)
# Solve
u = spsolve(L, rhs).reshape(grid.shape)
# Check error
u_exact = np.sin(np.pi * X) * np.sin(np.pi * Y)
print(f"Max error: {np.max(np.abs(u - u_exact)):.2e}")
The Chebyshev spectral method should give an error on the order of \(10^{-10}\) or smaller with 30 points per side.
With the Operator API, the same problem is three lines:
grid = Grid(x=chebyshev(30, 0.0, 1.0), y=chebyshev(30, 0.0, 1.0))
rhs = lambda x, y: -2 * np.pi**2 * np.sin(np.pi * x) * np.sin(np.pi * y)
u = grid.laplacian_operator().solve(rhs, bcs=0)
Tip
For mixed boundary conditions, simply put different BC types in the list. For example, Dirichlet on the left and right, Neumann on top and bottom:
bcs = [
DirichletBC(grid.faces["0_low"], value=0.0),
DirichletBC(grid.faces["0_high"], value=1.0),
NeumannBC(grid.faces["1_low"], value=0.0),
NeumannBC(grid.faces["1_high"], value=0.0),
]