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:
  • grid (Grid) – The numerical grid.

  • axis_index (int) – Which axis this face belongs to.

  • side (str) – "low" or "high".

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 -1 for the "low" face (outward normal points in the negative axis direction) and +1 for "high".

property shape: tuple[int, ...]

Shape of arrays restricted to this face.

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.0 for Cartesian grids.

integrate(f: NDArray) → float[source]

Integrate a function over this face.

Parameters:

f (NDArray) – Either an array of shape grid.shape (restricted to the face automatically) or an array of shape shape.

Returns:

The surface integral (including the surface element on curvilinear grids). For 1D grids the face is a single point and its value is returned.

Return type:

float

flux(*v: NDArray) → float[source]

Outward flux \(\int \mathbf{v}\cdot\mathbf{n}\, dA\) of a vector field.

Parameters:

*v (NDArray) – The (physical) components of the vector field, one per axis.

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 +1 on the "high" face and -1 on 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().

apply_to_system(L: spmatrix, rhs: NDArray) → tuple[spmatrix, NDArray][source]

Replace boundary rows with the normal-derivative operator row.

Uses the full differentiation matrix from Diff.

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().

apply_to_system(L: spmatrix, rhs: NDArray) → tuple[spmatrix, NDArray][source]

Replace boundary rows with a * I + b * sign * D.

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, Neumann or Robin spec – applied to every boundary face,

    • a bound BoundaryCondition or a list of them – used as is,

    • a dict {face_key: spec_or_value}. Face keys are those of Grid.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']