Metadata-Version: 2.4
Name: groundfield
Version: 0.7.0
Summary: Numerical field computation for grounding systems (PDE / field model, coupling to groundinsight)
License: MIT
License-File: LICENSE
Author: Christian Ehlert
Author-email: christian.ehlert@mailbox.org
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: geo
Provides-Extra: groundinsight
Requires-Dist: groundinsight (>=0.3) ; extra == "groundinsight"
Requires-Dist: matplotlib (>=3.9.2,<4.0.0)
Requires-Dist: numpy (>=2.1.0,<3.0.0)
Requires-Dist: pandas (>=3.0.2,<4.0.0)
Requires-Dist: polars (>=1.5.0,<2.0.0)
Requires-Dist: pydantic (>=2.8.2,<3.0.0)
Requires-Dist: pyproj (>=3.6,<4.0) ; extra == "geo"
Requires-Dist: requests (>=2.32,<3.0) ; extra == "geo"
Requires-Dist: scipy (>=1.14.1,<2.0.0)
Requires-Dist: shapely (>=2.0,<3.0) ; extra == "geo"
Requires-Dist: sympy (>=1.13.2,<2.0.0)
Project-URL: Documentation, https://ce1ectric.github.io/groundfield/
Project-URL: Repository, https://github.com/Ce1ectric/groundfield
Description-Content-Type: text/markdown

# groundfield

**Numerical field computation for grounding systems.**

[![Python versions](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`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](https://ce1ectric.github.io/groundfield/)
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](https://ce1ectric.github.io/groundfield/concepts/)
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](docs/examples/08_osm_pipeline.md) 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 AP1 penetration
  sweeps grow the foundation-equipped subset monotonically. See
  the [measurement-distance comparison
  example](docs/examples/07_measurement_distance.md) 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](docs/examples/06_tn_model.md)
  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**.

```bash
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`):

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

The documentation extras live in an optional Poetry group:

```bash
poetry install --with docs
```

## Quickstart

```python
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](https://ce1ectric.github.io/groundfield/quickstart/)
and the [examples gallery](https://ce1ectric.github.io/groundfield/examples/).

## 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

```bash
# 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.

```bash
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](LICENSE).

