Metadata-Version: 2.4
Name: groundfield
Version: 0.14.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.

## What's new

`groundfield` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
and [Semantic Versioning](https://semver.org/spec/v2.0.0.html). See the
**[changelog](https://ce1ectric.github.io/groundfield/changelog/)** for the
full release history and the forward-looking roadmap.

Recent highlights:

- **0.12 — `PolylineElectrode`.** Foundation rings follow the real building
  outline (a closed polyline) instead of the oriented bounding rectangle,
  removing the perimeter bias and the coincident-conductor artefacts that
  appear at AP1 scale.
- **0.11 — one-shot mutual grounding-impedance matrix** plus an audit-driven
  hardening of the inductive (Carson / Sommerfeld / Neumann) and cross-layer
  stacks.
- **0.7 — `OrtsnetzLayout`.** Imperative TN-Ortsnetz builder with a
  Manhattan-routed PEN router and a simulated fall-of-potential measurement.

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

