Boundary Conditions¶
Boundary conditions can be applied to solution arrays and to the sparse
matrix systems that arise from discretised differential equations. Numgrids
supports Dirichlet, Neumann, and Robin boundary conditions.
BoundaryFace identifies which face of the domain a
condition is imposed on, and apply_bcs() applies a collection
of conditions in a single call.
- class numgrids.BoundaryFace(grid: Grid, axis_index: int, side: str)[source]¶
A selection of boundary points on one face of a grid.
For an N-dimensional grid, each non-periodic axis contributes two faces:
"low"(index 0 along that axis) and"high"(last index). Ends that are not a boundary have no face: the origin of a radial axis, the poles of a colatitude axis and the ends at infinity of the axes on unbounded domains.- Parameters:
- property key: str¶
The canonical key of this face in
Grid.faces, e.g."0_low".
- property mask: NDArray¶
Boolean mask of shape
grid.shape, True on this face.
- property flat_indices: NDArray¶
Flat (1-D) indices of this face’s points in the ravelled grid.
- property normal_sign: int¶
Sign of the outward unit normal along the face’s axis.
Returns
-1for the"low"face (outward normal points in the negative axis direction) and+1for"high".
- property coords: tuple[NDArray, ...]¶
Meshed coordinates (all grid dimensions) restricted to this face.
- restrict(f: NDArray) NDArray[source]¶
Restrict a meshed function to this face.
- Parameters:
f (NDArray) – Array of shape
grid.shape.- Returns:
Array of shape
shape.- Return type:
NDArray
- normal_derivative(f: NDArray) NDArray[source]¶
Outward normal derivative \(\partial f / \partial n\) on this face.
On curvilinear grids the physical normal derivative \(\pm (1/h_i)\, \partial f / \partial q_i\) is returned.
- Parameters:
f (NDArray) – Array of shape
grid.shape.- Returns:
Array of shape
shape.- Return type:
NDArray
- property area_element: float | NDArray¶
Surface element on this face (product of the other scale factors).
1.0for Cartesian grids.
- class numgrids.DirichletBC(face: BoundaryFace, value=0.0)[source]¶
Dirichlet boundary condition: \(u = g\) on a boundary face.
- Parameters:
face (BoundaryFace) – The boundary face.
value (float, NDArray, or callable) – The prescribed boundary value g.
- apply(u: NDArray) NDArray[source]¶
Set u to g on the boundary face (in-place).
- Returns:
The modified array (same object as u).
- Return type:
NDArray
- apply_to_system(L: spmatrix, rhs: NDArray) tuple[spmatrix, NDArray][source]¶
Replace boundary rows in L with identity rows and set rhs = g.
- Parameters:
L (spmatrix) – System matrix of shape
(grid.size, grid.size).rhs (NDArray) – Right-hand side vector of shape
(grid.size,).
- Returns:
Modified
(L, rhs).- Return type:
tuple of (spmatrix, NDArray)
- class numgrids.NeumannBC(face: BoundaryFace, value=0.0)[source]¶
Neumann boundary condition: \(\partial u / \partial n = g\).
The outward normal derivative is
sign * du/d(axis)where sign is+1on the"high"face and-1on the"low"face. On curvilinear grids the derivative is taken with respect to the coordinate (not the arc length); this makes no difference for homogeneous conditions.- Parameters:
face (BoundaryFace) – The boundary face.
value (float, NDArray, or callable) – The prescribed normal-derivative value g.
- apply(u: NDArray) NDArray[source]¶
Adjust the boundary layer of u so that the discrete normal derivative approximates g (first-order, in-place).
For higher accuracy, prefer
apply_to_system().
- class numgrids.RobinBC(face: BoundaryFace, a, b, value=0.0)[source]¶
Robin boundary condition: \(a\,u + b\,\partial u/\partial n = g\).
The coefficients may vary along the face: like the value, they can be arrays matching the face or callables of the face coordinates, e.g. for Newton’s law of cooling \(h\,u + k\,\partial u/\partial n = h\,u_\infty\) with a conductivity \(k\) that depends on the position.
- Parameters:
face (BoundaryFace) – The boundary face.
a (float, NDArray, or callable) – Coefficient of u.
b (float, NDArray, or callable) – Coefficient of the normal derivative.
value (float, NDArray, or callable) – The prescribed value g.
- apply(u: NDArray) NDArray[source]¶
Not supported for Robin conditions; use
apply_to_system().
- numgrids.apply_bcs(bcs, L: spmatrix, rhs: NDArray, grid: Grid | None = None) tuple[spmatrix, NDArray][source]¶
Apply a sequence of boundary conditions to a linear system.
Conditions are applied in list order; for overlapping points (e.g. corners) the last condition wins.
- Parameters:
bcs (list of BoundaryCondition, or any spec accepted by
resolve_bcs()) – Boundary conditions to apply. Compact specs (dicts, scalars) require grid.L (spmatrix) – System matrix of shape
(grid.size, grid.size).rhs (NDArray) – Right-hand side vector of shape
(grid.size,).grid (Grid, optional) – Needed only for compact specifications.
- Return type:
tuple of (spmatrix, NDArray)
Compact specifications¶
Unbound specifications are attached to faces when used as dictionary values
in Operator.solve,
Operator.eig, evolve() or
resolve_bcs().
- class numgrids.Dirichlet(value=0.0)[source]¶
Dirichlet condition u = value, to be bound to a face later.
Examples
>>> from numgrids import Grid, Dirichlet, Neumann, chebyshev >>> grid = Grid(x=chebyshev(10, 0, 1)) >>> bcs = {"x_low": Dirichlet(1.0), "x_high": Neumann(0.0)}
- class numgrids.Neumann(value=0.0)[source]¶
Neumann condition du/dn = value, to be bound to a face later.
- class numgrids.Robin(a, b, value=0.0)[source]¶
Robin condition a u + b du/dn = value, to be bound to a face later.
a, b and value are numbers, arrays matching the face, or callables of the face coordinates.
- class numgrids.TimeDependent(func: Callable)[source]¶
A boundary value that changes in time, for
evolve().- Parameters:
func (callable) –
func(t)returns the boundary value at time t: a scalar, an array matching the face, or a callable of the face coordinates (as for time-independent values).
Examples
A rod whose left end is heated periodically, while the right end is insulated:
>>> import numpy as np >>> from numgrids import Grid, Neumann, TimeDependent, chebyshev, evolve >>> grid = Grid(x=chebyshev(20, 0, 1)) >>> bcs = {"x_low": TimeDependent(lambda t: np.sin(t)), "x_high": Neumann(0)} >>> result = evolve(grid, grid.laplacian_operator(), np.zeros(grid.shape), (0, 2), ... bcs=bcs, method="BDF") >>> bool(np.isclose(result.final[0], np.sin(2))) True
- numgrids.resolve_bcs(grid: Grid, bcs) list[BoundaryCondition][source]¶
Convert a compact boundary condition specification to a list.
- Parameters:
grid (Grid) – The grid the conditions refer to.
bcs (None, scalar, callable, BCSpec, BoundaryCondition, list or dict) –
None– no conditions,a scalar, array or callable – Dirichlet condition with that value on every boundary face,
a
Dirichlet,NeumannorRobinspec – applied to every boundary face,a bound
BoundaryConditionor a list of them – used as is,a dict
{face_key: spec_or_value}. Face keys are those ofGrid.faces("0_low","x_high", …). The key"all"applies to every face; specific keys override it. Plain values mean Dirichlet conditions.
- Return type:
list of BoundaryCondition
Examples
>>> from numgrids import Grid, Neumann, chebyshev >>> from numgrids.boundary import resolve_bcs >>> grid = Grid(x=chebyshev(10, 0, 1), y=chebyshev(10, 0, 1)) >>> bcs = resolve_bcs(grid, {"all": 0, "y_high": Neumann(1)}) >>> [type(bc).__name__ for bc in bcs] ['DirichletBC', 'DirichletBC', 'DirichletBC', 'DirichletBC', 'NeumannBC']