Skip to content

Boundary conditions

The :mod:groundfield.boundary module defines the :class:BoundaryConditions model that a :class:World carries. The image-method, MoM and Sommerfeld backends implicitly assume a Dirichlet far field (φ → 0) and a Neumann surface (∂φ/∂n = 0 at z = 0); the explicit fields on :class:BoundaryConditions are preserved for forward-compatibility with the upcoming FEM backend.

Mathematical / physical model

groundfield solves the quasi-static grounding problem. Below roughly 1 kHz the displacement current in the soil is negligible, so the leakage current density follows Ohm's law \(\vec{J} = \sigma\,\vec{E} = -\sigma\,\nabla\varphi\) and charge conservation \(\nabla\cdot\vec{J} = 0\) in the source-free bulk reduces the potential to Laplace's equation

\[ \nabla\cdot\!\bigl(\sigma(\vec{r})\,\nabla\varphi(\vec{r})\bigr) = 0, \]

which becomes \(\nabla^2\varphi = 0\) inside every homogeneous soil region. Injected electrode currents are not a volume source term; they enter through the electrode boundary (the solver's right-hand side), which is why they are not part of :class:BoundaryConditions.

A well-posed boundary-value problem needs three conditions, and these are exactly the fields this module carries:

  • Far field (far_field, remote earth). Dirichlet \(\varphi \to 0\) as \(|\vec{r}| \to \infty\). The integral / image-charge backends realise it through the \(1/r\) decay of the free-space Green's function, so all reported potentials are referred to remote earth.
  • Soil surface (surface, air–soil interface at \(z = 0\)). Homogeneous Neumann \(\partial\varphi/\partial n = \partial\varphi/\partial z = 0\): no leakage current crosses into the insulating air. The backends realise it with a mirror image charge at \(z \to -z\), which doubles the potential of a buried source in the lower half-space.
  • Potential datum (reference_node). Fixes the additive gauge of \(\varphi\). With the default Dirichlet far field the datum is remote earth; an explicit reference node is reserved for the FEM backend.

At an interface between two soil layers of conductivity \(\sigma_k\) and \(\sigma_{k+1}\) the potential \(\varphi\) and the normal current density \(J_n = \sigma\,\partial_n\varphi\) are continuous; those interface conditions are handled by the layered Green's functions in the coupling package, not by this module.

Validity. Linear, isotropic, piecewise-homogeneous soil in the quasi-static regime. Frequency-dependent earth-return (inductive) effects are treated as a separate additive correction on the branch impedance (see coupling), not as part of this electrostatic boundary-value problem.

Revert-warning contract (0.5.0)

Calling :meth:World.set_boundary_conditions with a non-default value emits a :class:UserWarning so the user does not silently configure a value that the v0.2.0 backends ignore. Reverting back to the default value also emits a :class:UserWarning — see the implementation note in the CHANGELOG.

API reference

boundary

Boundary conditions for the field computation.

The boundary configuration bundles all assumptions imposed at the boundary of the computational domain:

  • far_field: behaviour at infinity (Dirichlet \(\varphi = 0\), Neumann \(\partial_n \varphi = 0\)). For grounding systems, Dirichlet at infinity is the standard assumption ("remote earth").
  • surface: condition at the soil surface (\(z = 0\)). Default is Neumann (no current flow into the air).
  • reference_node: optional reference node that fixes the zero point of the potential.
Implementation status (v0.2.0)

The boundary fields are accepted on every :class:World and round-trip through serialisation, but the integral / image-charge backends in groundfield.solver enforce the defaults implicitly:

  • far_field = "dirichlet" is hard-wired through the \(1/r\) Green's-function decay.
  • surface = "neumann" is hard-wired through the air-side image charge at \(z \to -z\).
  • reference_node is not consulted; all potentials are reported relative to remote earth (\(\varphi \to 0\) at infinity).

Setting any field to a non-default value via :meth:groundfield.world.World.set_boundary_conditions therefore emits a :class:UserWarning. The fields remain reserved for the future :mod:groundfield.solver.fem backend, which will resolve them explicitly.

BoundaryConditions

Bases: BaseModel

Boundary-condition configuration of a :class:World.

Notes

The integral / image-charge backends in groundfield.solver use the defaults implicitly (far_field="dirichlet", surface="neumann", reference_node=None) and ignore any other value. The fields are reserved for the upcoming FEM backend. See the module docstring for a longer discussion.