groundfield 0.8.0

Numerical field computation for grounding systems (PDE / field model, coupling to groundinsight)

groundfield

Numerical field computation for grounding systems.

groundfield is an open-source Python package for the physical reference modelling of networked grounding systems. Within the groundmeas / groundinsight / groundfield software family, groundfield covers the field-theoretical side: soil models, electrode geometries, conductors and their couplings are formulated as a 3-D problem in the soil and solved numerically. Field profiles, potential curves and current distributions are reduced to equivalent rho-f models that can be handed over to groundinsight as a BusType. See the documentation for full details.

• Documentation: https://ce1ectric.github.io/groundfield/
• Source code: https://github.com/Ce1ectric/groundfield
• Issue tracker: https://github.com/Ce1ectric/groundfield/issues

Position within the software family

  groundmeas   ──▶   groundinsight   ◀──   groundfield
  (measurement)      (reduced network            (field model,
                      model)                      PDE reference)

groundfield provides the physically grounded reference model from which reduced impedance and multi-port representations are derived. These travel into groundinsight as BusType / BranchType formulas where they can be reconciled with measurement data from groundmeas.

Scope

groundfield covers layered soil (two-layer and multi-layer models), typical electrode geometries (ring, strip, rod, foundation, mesh), conductors, cable shields and PEN with their mutual coupling, the Carson 1926 and rigorous Sommerfeld earth-return corrections, cross- layer electrodes, current and potential distribution in the soil, the influence of the measurement geometry on the grounding-measurement result, and the derivation of reduced rho-f models for groundinsight. See the scope and concepts page for the full list with references to the underlying ADRs.

New in 0.7.0

• OrtsnetzLayout — imperative TN-Ortsnetz builder. New entry point in groundfield.generators for composing a single deterministic LV network from a real OSM extract: ingest footprints, drop the substation + KVS by lat/lon or local ENU metres, route PEN cables in strict Manhattan geometry around the foundations, connect every house to its closest cable. Everything is one method per step on the layout — see the OSM-pipeline example for the full workflow on a real village.

• Manhattan-routed PEN cable router. New groundfield.generators.manhattan_routing.route_manhattan runs 4-connected A* on a regular Manhattan grid of user-chosen cell size and avoids every building's bounding rectangle inflated by a configurable clearance. PEN cables therefore never cross a foundation polygon. An escape_radius_m safety valve handles substations that land inside or right next to a foundation in a real OSM extract.

• Simulated fall-of-potential measurement. OrtsnetzLayout.add_auxiliary_electrode drops a Hilfserder (default: 3 × 0.5 m rod triangle, parallel-bonded) at a user-controlled distance / direction from the substation. OrtsnetzLayout.add_voltage_probe adds the Spannungssonde as a pure sampling point (no rod in the world → no field perturbation), either inline along the substation → aux axis or 90° rotated from it. measured_grounding_impedance returns the simulated meter reading $(\varphi_\text{sub} - \varphi_\text{probe}) / I_\text{src}$ — with a probe_xy override that lets a single solve yield multiple probe readings. verify_current_balance is the Kirchhoff plausibility check that confirms the loop is physically closed in the engine's view.

• Reproducible foundation-electrode penetration mask. OrtsnetzLayout.foundation_mask(penetration, salt=0) returns a deterministic per-house bool list derived from a stable MD5 hash of each footprint's OSM id. Same (p, salt) → same mask every time, and the mask is nested in p so penetration sweeps grow the foundation-equipped subset monotonically. See the measurement-distance comparison example for a full study including surface-potential galleries and a dual-probe (0° / 90°) Hilfserder-distance sweep.

• RadialTrunkTopology for TnNetworkGenerator. New PEN backbone option alongside the legacy star-KVS layout: the substation feeds N radial feeders with a finite slot budget per source; once exhausted, additional KVS are inserted along the trunk axis. See the TN-Model example for a complete walk-through.

• Surface-potential plot with TwoSlopeNorm. OrtsnetzLayout.plot_surface_potential defaults to a TwoSlopeNorm-based diverging colour map (RdBu_r) centred at zero so the deep Hilfserder trough and the small substation + foundation trumpet are both visible at full colour resolution.

Installation

groundfield requires Python 3.12 or newer.

git clone https://github.com/Ce1ectric/groundfield.git
cd groundfield
poetry install

For OSM-driven building footprints (ADR-0011), enable the optional geo extra (pulls in requests, shapely, pyproj):

pip install groundfield[geo]
# or, from a Poetry checkout
poetry install --extras geo

The documentation extras live in an optional Poetry group:

poetry install --with docs

Quickstart

import groundfield as gf

soil = gf.TwoLayerSoil(rho_1=100.0, rho_2=500.0, h_1=2.0)
world = gf.create_world(soil=soil)
gf.create_electrode(
    world, "ring", name="g1",
    center=(0.0, 0.0, 0.8), radius=5.0, wire_radius=0.005,
)
gf.create_source(world, attached_to="g1", magnitude=1.0)

engine = gf.create_engine(backend="image",
                          frequencies=[50.0, 150.0, 250.0])
result = world.solve(engine)
print(result.cluster_impedance("g1"))

backend="image" auto-dispatches to the matching layered backend. The full backend list, the rho-f export to groundinsight and the TnNetworkGenerator are documented in Quickstart and the examples gallery.

Guiding principles

• The PDE / field model is a reference, not the end product. The solver must be instrumented so that every solution can be reduced to an identification-friendly form.
• Measurability before accuracy. The relevant frequency range is < 1 kHz; this allows simplified soil models and fast solvers.
• Grey-box, not black-box. Geometric and material inputs stay visible; only the parts that are not physically prescribed are identified.

Development

# Tests with coverage
poetry run pytest --cov=groundfield

# Formatting
poetry run black src tests scripts

# Local documentation
poetry install --with docs
poetry run mkdocs serve

Releases are triggered through the Poetry script. It updates the version in pyproject.toml, src/groundfield/__init__.py, and CITATION.cff, moves the [Unreleased] block of CHANGELOG.md into a new section, and creates an annotated tag.

poetry run release patch
poetry run release minor
poetry run release major
poetry run release set 1.2.3

Citing

If you use groundfield in academic work, please cite according to the metadata in CITATION.cff.

License

groundfield is released under the MIT license.