detectability 0.4.0__tar.gz → 0.5.0__tar.gz

{detectability-0.4.0/src/detectability.egg-info → detectability-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.4.0
+Version: 0.5.0
 Summary: Pre-survey detectability, modelled and reproducible: forward-modelled gravity and magnetic responses, station spacing and a detectability verdict for near-surface targets.
 Author: Mükremin Nergiz
 License-Expression: BSD-3-Clause
@@ -30,6 +30,8 @@ Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Provides-Extra: validation
 Requires-Dist: harmonica==0.7.0; extra == "validation"
+Provides-Extra: ert
+Requires-Dist: pygimli>=1.5; extra == "ert"
 Dynamic: license-file
 
 # Detectability
@@ -69,7 +71,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.4.0: sphere in limestone
+Detectability 0.5.0: sphere in limestone
 - gravity: peak 114 µGal, noise 11.2 µGal, S/N 10.2: clearly detectable
   stations every 5 m or less, profile at least 153 m long
 - magnetic: peak 0.462 nT, noise 2 nT, S/N 0.231: not detectable
@@ -87,10 +89,13 @@ Methods: `gravity`, `magnetic` (total-field anomaly) and, on request, `gradient`
 (lower minus upper sensor, in nT over the baseline), with presets for the Bartington Grad601, Sensys FGM650, Foerster
 FEREX 4.034 and GEM GSM-19G; and, on request, `gpr`: ground-penetrating radar, the echo of the target's top against
 the system's detection limit (radar range equation), with velocity, attenuation, antenna frequency, trace spacing and
-recording window. The defaults are `gravity` and `magnetic`:
+recording window; and, on request, `ert`: electrical resistivity tomography, a 2D finite-element model of the target
+under a line of electrodes (dipole-dipole, Wenner, Schlumberger or gradient array), the change it makes to the
+apparent resistivities, and whether an inversion of noisy synthetic data recovers it. ERT needs
+[pyGIMLi](https://www.pygimli.org): `pip install "detectability[ert]"`. The defaults are `gravity` and `magnetic`:
 
 ```python
-evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr", "ert"])
 ```
 
 ## Modules
@@ -101,6 +106,7 @@ evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
 | `gravity` | sphere, horizontal cylinder, right rectangular prism (Nagy; Plouff) and its gradient tensor, vertical cylinder (exact, by a rim integral) and its gradient tensor, vertical step, dyke, 2D polygon (Talwani; Won & Bevis) |
 | `magnetics` | total-field anomaly: sphere, horizontal cylinder, prism, vertical cylinder, 2D polygon, dyke (any dip), vertical contact; induced and remanent magnetisation (a gradiometer reading is the difference at two sensor heights) |
 | `gpr` | ground-penetrating radar: exact velocity and attenuation of a lossy medium, normal-incidence reflection coefficient, target-size factor (geometric optics, Rayleigh regime, Fresnel zone), echo against system performance; typical permittivity and conductivity (Davis & Annan 1989) |
+| `ert` | electrical resistivity tomography with pyGIMLi (optional): electrode layout, 2D finite-element forward model, inversion and recovery check; typical resistivities (Loke 1999, after Keller & Frischknecht 1966) |
 | `igrf` | IGRF-14 main field from location and date, from the official IAGA coefficients |
 | `rocks` | typical densities and magnetic susceptibilities with their ranges (Telford et al. 1990) |
 | `detect` | instrument presets with their sources (gravimeters, magnetometers, gradiometers), field noise, signal-to-noise ratio, verdict, station spacing, profile length |
@@ -145,6 +151,8 @@ python tools/harmonica_reference.py --check
 | Analytical limit | GPR, reflection coefficient | (√ε1 − √ε2)/(√ε1 + √ε2) for lossless media | 0.0e+00 % | 1.0e-10 % |
 | Analytical limit | GPR, very large sphere | Flat reflector at the same range | 5.0e-06 % | 1.0e-04 % |
 | Published values | GPR, velocity of common materials | Davis & Annan (1989) table velocities (rounded to 0.01 m/ns) | 4.92 % | 6 % |
+| Analytical limit | ERT, homogeneous ground | Apparent resistivity equals the true resistivity | 0.297 % | 1 % |
+| Analytical limit | ERT, two layers, Wenner sounding | Image-series solution for two layers | 0.144 % | 2 % |
 | Independent code | Prism, gravity | Harmonica 0.7.0 prism_gravity | 3.0e-12 % | 1.0e-08 % |
 | Independent code | Prism, magnetic | Harmonica 0.7.0 prism_magnetic | 4.8e-13 % | 1.0e-08 % |
 | Independent code | Sphere, gravity | Harmonica 0.7.0 point_gravity | 3.9e-14 % | 1.0e-10 % |
@@ -172,7 +180,7 @@ field noise (0.5 nT) is an assumption, not a published figure: soil, heading and
 
 See [CITATION.cff](https://github.com/mukremin-nergiz/detectability/blob/main/CITATION.cff), or:
 
-> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.4.0) [Computer software].
+> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.5.0) [Computer software].
 > Zenodo. https://doi.org/10.5281/zenodo.23931815
 
 The DOI above always resolves to the latest version; each release also has its own DOI on Zenodo. Changes between

{detectability-0.4.0 → detectability-0.5.0}/README.md

@@ -35,7 +35,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.4.0: sphere in limestone
+Detectability 0.5.0: sphere in limestone
 - gravity: peak 114 µGal, noise 11.2 µGal, S/N 10.2: clearly detectable
   stations every 5 m or less, profile at least 153 m long
 - magnetic: peak 0.462 nT, noise 2 nT, S/N 0.231: not detectable
@@ -53,10 +53,13 @@ Methods: `gravity`, `magnetic` (total-field anomaly) and, on request, `gradient`
 (lower minus upper sensor, in nT over the baseline), with presets for the Bartington Grad601, Sensys FGM650, Foerster
 FEREX 4.034 and GEM GSM-19G; and, on request, `gpr`: ground-penetrating radar, the echo of the target's top against
 the system's detection limit (radar range equation), with velocity, attenuation, antenna frequency, trace spacing and
-recording window. The defaults are `gravity` and `magnetic`:
+recording window; and, on request, `ert`: electrical resistivity tomography, a 2D finite-element model of the target
+under a line of electrodes (dipole-dipole, Wenner, Schlumberger or gradient array), the change it makes to the
+apparent resistivities, and whether an inversion of noisy synthetic data recovers it. ERT needs
+[pyGIMLi](https://www.pygimli.org): `pip install "detectability[ert]"`. The defaults are `gravity` and `magnetic`:
 
 ```python
-evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr", "ert"])
 ```
 
 ## Modules
@@ -67,6 +70,7 @@ evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
 | `gravity` | sphere, horizontal cylinder, right rectangular prism (Nagy; Plouff) and its gradient tensor, vertical cylinder (exact, by a rim integral) and its gradient tensor, vertical step, dyke, 2D polygon (Talwani; Won & Bevis) |
 | `magnetics` | total-field anomaly: sphere, horizontal cylinder, prism, vertical cylinder, 2D polygon, dyke (any dip), vertical contact; induced and remanent magnetisation (a gradiometer reading is the difference at two sensor heights) |
 | `gpr` | ground-penetrating radar: exact velocity and attenuation of a lossy medium, normal-incidence reflection coefficient, target-size factor (geometric optics, Rayleigh regime, Fresnel zone), echo against system performance; typical permittivity and conductivity (Davis & Annan 1989) |
+| `ert` | electrical resistivity tomography with pyGIMLi (optional): electrode layout, 2D finite-element forward model, inversion and recovery check; typical resistivities (Loke 1999, after Keller & Frischknecht 1966) |
 | `igrf` | IGRF-14 main field from location and date, from the official IAGA coefficients |
 | `rocks` | typical densities and magnetic susceptibilities with their ranges (Telford et al. 1990) |
 | `detect` | instrument presets with their sources (gravimeters, magnetometers, gradiometers), field noise, signal-to-noise ratio, verdict, station spacing, profile length |
@@ -111,6 +115,8 @@ python tools/harmonica_reference.py --check
 | Analytical limit | GPR, reflection coefficient | (√ε1 − √ε2)/(√ε1 + √ε2) for lossless media | 0.0e+00 % | 1.0e-10 % |
 | Analytical limit | GPR, very large sphere | Flat reflector at the same range | 5.0e-06 % | 1.0e-04 % |
 | Published values | GPR, velocity of common materials | Davis & Annan (1989) table velocities (rounded to 0.01 m/ns) | 4.92 % | 6 % |
+| Analytical limit | ERT, homogeneous ground | Apparent resistivity equals the true resistivity | 0.297 % | 1 % |
+| Analytical limit | ERT, two layers, Wenner sounding | Image-series solution for two layers | 0.144 % | 2 % |
 | Independent code | Prism, gravity | Harmonica 0.7.0 prism_gravity | 3.0e-12 % | 1.0e-08 % |
 | Independent code | Prism, magnetic | Harmonica 0.7.0 prism_magnetic | 4.8e-13 % | 1.0e-08 % |
 | Independent code | Sphere, gravity | Harmonica 0.7.0 point_gravity | 3.9e-14 % | 1.0e-10 % |
@@ -138,7 +144,7 @@ field noise (0.5 nT) is an assumption, not a published figure: soil, heading and
 
 See [CITATION.cff](https://github.com/mukremin-nergiz/detectability/blob/main/CITATION.cff), or:
 
-> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.4.0) [Computer software].
+> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.5.0) [Computer software].
 > Zenodo. https://doi.org/10.5281/zenodo.23931815
 
 The DOI above always resolves to the latest version; each release also has its own DOI on Zenodo. Changes between

{detectability-0.4.0 → detectability-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "detectability"
-version = "0.4.0"
+version = "0.5.0"
 description = "Pre-survey detectability, modelled and reproducible: forward-modelled gravity and magnetic responses, station spacing and a detectability verdict for near-surface targets."
 readme = "README.md"
 keywords = ["geophysics", "gravity", "magnetics", "survey design", "near-surface", "forward modelling", "IGRF"]
@@ -38,6 +38,8 @@ Citation = "https://doi.org/10.5281/zenodo.23931815"
 test = ["pytest>=7"]
 # Recomputes the "Independent code" reference values (tools/harmonica_reference.py); not needed to use the library.
 validation = ["harmonica==0.7.0"]
+# Electrical resistivity tomography (method "ert"): finite elements and inversion with pyGIMLi.
+ert = ["pygimli>=1.5"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

{detectability-0.4.0 → detectability-0.5.0}/src/detectability/__init__.py

@@ -1,6 +1,6 @@
 """Detectability: pre-survey detectability, modelled and reproducible."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 from .survey import DEFAULT_METHODS, METHODS, SHAPES, Report, Survey, Target, evaluate  # noqa: E402
 

detectability-0.5.0/src/detectability/data/ert_reference.json

@@ -0,0 +1,40 @@
+{
+ "pygimli": "1.6.1",
+ "doi": "10.1016/j.cageo.2017.07.011",
+ "halfspace_error_percent": 0.29701507707668995,
+ "wenner_two_layer": {
+  "rho1": 100.0,
+  "rho2": 10.0,
+  "h": 5.0,
+  "spacing": [
+   1.0,
+   2.0,
+   3.0,
+   5.0,
+   8.0,
+   12.0,
+   16.0,
+   20.0
+  ],
+  "model": [
+   99.61000261515714,
+   96.89634932280532,
+   91.18162883033095,
+   73.36750131129314,
+   46.680818102896644,
+   25.39363222503698,
+   16.284202471814222,
+   12.780339615225937
+  ],
+  "analytic": [
+   99.56748456281315,
+   96.90460006182809,
+   91.1609264135159,
+   73.39044630419616,
+   46.53753517471967,
+   25.330265325884227,
+   16.376777534327324,
+   12.860338899308598
+  ]
+ }
+}

{detectability-0.4.0 → detectability-0.5.0}/src/detectability/detect.py

@@ -76,7 +76,7 @@ DEFAULT_FIELD_NOISE_NT = 2.0     # quiet rural site after diurnal correction; ur
 # by less than about 0.5 nT over 1 m); change it for the site.
 DEFAULT_FIELD_NOISE_GRADIENT_NT = 0.5
 
-UNITS = {"gravity": "µGal", "magnetic": "nT", "gradient": "nT", "gpr": "× detection limit"}
+UNITS = {"gravity": "µGal", "magnetic": "nT", "gradient": "nT", "gpr": "× detection limit", "ert": "%"}
 
 
 def effective_noise(instrument: float, field_noise: float) -> float:

detectability-0.5.0/src/detectability/ert.py

@@ -0,0 +1,272 @@
+"""Electrical resistivity tomography (ERT): 2D forward model of a target under a line of electrodes, the change it
+makes to the apparent resistivities, and whether an inversion of noisy synthetic data recovers it.
+
+The finite-element modelling and the inversion use pyGIMLi (Rücker, Günther & Wagner 2017, Computers & Geosciences
+109, 106-123), an optional dependency: ``pip install "detectability[ert]"``. Without it the method is reported as not
+available. A service can run it instead: if pyGIMLi is missing and ``DETECTABILITY_ERT_URL`` is set, the request is
+sent there (the website does this; its ERT runs on a separate machine).
+
+What is computed, and the conventions:
+- Electrodes at equal spacing along a straight line centred over the target; arrays: dipole-dipole, Wenner,
+  Schlumberger or multiple gradient.
+- Apparent resistivities with and without the target on the same mesh; their ratio removes the mesh error. The data
+  anomaly is 100 (rho_a,target / rho_a,host - 1) %, and S/N is its largest absolute value over the data noise (%), with
+  the same thresholds as the other methods.
+- Recovery: the noisy data (the given noise level) are inverted (smoothness-constrained Gauss-Newton, pyGIMLi's
+  ERTManager, at most 6 iterations). The recovered contrast is the median model value inside the target over the median
+  outside. The target counts as recovered when that contrast has the right sign and reaches 20 % of the true contrast
+  in log scale or a factor of 1.5, whichever is smaller; otherwise a detectable verdict is lowered to marginal.
+- 2D: the target is infinitely long across the profile. A sphere is modelled as a horizontal cylinder of the same
+  diameter, which overstates its effect; the assumptions say so.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.request
+from dataclasses import dataclass
+
+import numpy as np
+
+# Resistivity ranges (ohm m), from Loke (1999), "Electrical imaging surveys for environmental and engineering
+# studies", Table 1, after Keller & Frischknecht (1966) and Daniels & Alberty (1966). "Typical" is the geometric
+# middle of the range. Air (a void) is effectively an insulator; it is modelled as 10^6 ohm m, beyond which the
+# anomaly no longer changes. Metal: iron, 9.074e-8 ohm m.
+RESISTIVITY: dict[str, tuple[float, float, float]] = {
+    "air": (1e6, 1e6, 1e6),
+    "granite": (7.07e4, 5e3, 1e6),
+    "basalt": (3.16e4, 1e3, 1e6),
+    "slate": (1.55e5, 6e2, 4e7),
+    "marble": (1.58e5, 1e2, 2.5e8),
+    "quartzite": (1.41e5, 1e2, 2e8),
+    "sandstone": (1.79e2, 8.0, 4e3),
+    "shale": (2.0e2, 20.0, 2e3),
+    "limestone": (1.41e2, 50.0, 4e2),
+    "clay": (10.0, 1.0, 100.0),
+    "alluvium": (89.4, 10.0, 800.0),
+    "water": (31.6, 10.0, 100.0),
+    "fresh water": (31.6, 10.0, 100.0),
+    "sea water": (0.2, 0.2, 0.2),
+    "metal": (9.074e-8, 9.074e-8, 9.074e-8),
+}
+
+ARRAYS = {"dipole-dipole": "dd", "wenner": "wa", "schlumberger": "slm", "gradient": "gr"}
+DEFAULT_ARRAY = "dipole-dipole"
+DEFAULT_ELECTRODES = 48
+DEFAULT_NOISE_PERCENT = 3.0
+RECOVERY_THRESHOLD = 0.2
+RECOVERED_FACTOR = 1.5
+MIN_RESISTIVITY = 1e-3   # metal is modelled as 10^-3 ohm m (a perfect conductor for the survey; avoids a singular system)
+DEFAULT_SERVICE_TIMEOUT = 150
+
+
+def resistivity(name: str) -> float:
+    try:
+        return RESISTIVITY[name][0]
+    except KeyError:
+        raise KeyError(f"no resistivity for {name!r}; known: {', '.join(sorted(RESISTIVITY))}") from None
+
+
+def available() -> bool:
+    try:
+        import pygimli  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def _nice_down(v: float) -> float:
+    e = np.floor(np.log10(v))
+    for m in (5.0, 2.0, 1.0):
+        if m * 10**e <= v:
+            return float(m * 10**e)
+    return float(5 * 10 ** (e - 1))
+
+
+def default_spacing(depth_needed: float, electrodes: int) -> float:
+    """Electrode spacing whose spread (electrodes - 1 spacings) is about six times the depth that must be seen."""
+    return max(0.1, _nice_down(6.0 * depth_needed / (electrodes - 1)))
+
+
+@dataclass
+class Geometry:
+    polygon: list          # target outline (x, z), z negative downwards, in the profile frame centred on the target
+    depth_needed: float    # m: the bottom of the target (or of its useful part) that the survey must reach
+    area: float            # m^2 of the 2D outline
+
+
+def geometry(t) -> Geometry:
+    """2D outline of a ``survey.Target``."""
+    r = (t.size or 0) / 2
+    if t.shape in ("sphere", "horizontal_cylinder"):
+        zc = t.depth_top + r
+        ang = np.linspace(0, 2 * np.pi, 48, endpoint=False)
+        return Geometry([(r * np.cos(a), -zc + r * np.sin(a)) for a in ang], zc + r, np.pi * r * r)
+    if t.shape in ("vertical_cylinder", "prism"):
+        w = t.size / 2
+        return Geometry([(-w, -t.depth_top), (w, -t.depth_top), (w, -t.depth_bottom), (-w, -t.depth_bottom)],
+                        t.depth_bottom, 2 * w * (t.depth_bottom - t.depth_top))
+    if t.shape == "dyke":
+        h = t.depth_bottom - t.depth_top
+        dx = h / np.tan(np.radians(t.dip)) if abs(t.dip - 90) > 1e-9 else 0.0
+        w = t.size / 2
+        return Geometry([(-w, -t.depth_top), (w, -t.depth_top), (w + dx, -t.depth_bottom), (-w + dx, -t.depth_bottom)],
+                        t.depth_bottom, t.size * h)
+    if t.shape == "contact":
+        return Geometry([], t.depth_bottom, float("inf"))
+    raise ValueError(f"unknown shape {t.shape!r}")
+
+
+def run(t, s) -> dict:
+    """Model, assess and invert. Returns a plain dict (MethodResult fields) so a service can send it as JSON."""
+    import pygimli as pg
+    import pygimli.meshtools as mt
+    from pygimli.physics import ert as pgert
+
+    from . import detect
+
+    pg.setThreadCount(int(os.environ.get("DETECTABILITY_ERT_THREADS", "2")))
+    started = time.time()
+    rho_h = t.host_resistivity if t.host_resistivity is not None else resistivity(t.host)
+    rho_t = t.resistivity if t.resistivity is not None else resistivity(t.material)
+    rho_t = max(rho_t, MIN_RESISTIVITY)
+    if rho_h <= 0:
+        raise ValueError("host resistivity must be positive")
+    array = s.ert_array or DEFAULT_ARRAY
+    if array not in ARRAYS:
+        raise ValueError(f"unknown ERT array {array!r}; choose from {', '.join(ARRAYS)}")
+    n = int(s.ert_electrodes or DEFAULT_ELECTRODES)
+    if not 8 <= n <= 96:
+        raise ValueError("ert_electrodes must be between 8 and 96")
+    noise = s.ert_noise if s.ert_noise is not None else DEFAULT_NOISE_PERCENT
+    if not 0.1 <= noise <= 50:
+        raise ValueError("ert_noise must be between 0.1 and 50 %")
+    g = geometry(t)
+    a = s.ert_spacing or default_spacing(g.depth_needed, n)
+    if a <= 0:
+        raise ValueError("ert_spacing must be positive")
+    L = a * (n - 1)
+    x0 = -L / 2
+    elecs = np.linspace(x0, x0 + L, n)
+    scheme = pgert.createData(elecs=elecs, schemeName=ARRAYS[array])
+
+    pad = max(L, 4 * g.depth_needed)
+    depth = max(L / 2, 2.5 * g.depth_needed)
+    world = mt.createWorld(start=[x0 - pad, 0], end=[x0 + L + pad, -depth - pad], worldMarker=True)
+    if t.shape == "contact":
+        body = mt.createPolygon([(0, -t.depth_top), (x0 + L + pad, -t.depth_top), (x0 + L + pad, -t.depth_bottom),
+                                 (0, -t.depth_bottom)], isClosed=True, marker=2)
+    else:
+        body = mt.createPolygon(g.polygon, isClosed=True, marker=2, area=max((a / 4) ** 2, g.area / 200))
+    geom = world + body
+    for p in scheme.sensors():
+        geom.createNode(p)
+        geom.createNode(p - [0, a / 10])
+    mesh = mt.createMesh(geom, quality=33.5)
+
+    with_target = pgert.simulate(mesh, scheme=scheme, res=[[1, rho_h], [2, rho_t]], noiseLevel=0, verbose=False)
+    host_only = pgert.simulate(mesh, scheme=scheme, res=[[1, rho_h], [2, rho_h]], noiseLevel=0, verbose=False)
+    ra_t, ra_h = np.array(with_target["rhoa"]), np.array(host_only["rhoa"])
+    anomaly = 100.0 * (ra_t / ra_h - 1.0)
+
+    # Profile for the assessment: at each data midpoint, the largest change over the levels.
+    mid = np.array([(elecs[int(with_target["a"][i])] + elecs[int(with_target["b"][i])] +
+                     elecs[int(with_target["m"][i])] + elecs[int(with_target["n"][i])]) / 4
+                    for i in range(with_target.size())])
+    xs = np.unique(np.round(mid, 6))
+    prof = np.array([anomaly[np.isclose(mid, xv)][np.argmax(np.abs(anomaly[np.isclose(mid, xv)]))] for xv in xs])
+    assessment = detect.assess(xs, prof, noise, depth=t.depth_top, method="ert")
+    assessment.station_spacing = float(a)
+    assessment.profile_length = float(L)
+
+    details = {"array": array, "electrodes": n, "spacing_m": float(a), "spread_m": float(L), "data": int(scheme.size()),
+               "host_resistivity": float(rho_h), "target_resistivity": float(rho_t), "noise_percent": float(noise),
+               "max_anomaly_percent": float(np.max(np.abs(anomaly))), "inverted": False}
+
+    if s.ert_invert and t.shape != "contact":
+        rng = np.random.default_rng(1337)
+        data = pg.DataContainerERT(with_target)
+        data["rhoa"] = ra_t * (1 + rng.normal(0, noise / 100, len(ra_t)))
+        data["err"] = pg.Vector(len(ra_t), noise / 100)
+        mgr = pgert.ERTManager(data, verbose=False)
+        mgr.invert(lam=20, verbose=False, paraDepth=min(depth, max(1.5 * g.depth_needed, L / 5)), quality=33.6,
+                   paraMaxCellSize=max(a * a, g.area / 50), paraDX=0.5, maxIter=6)
+        cells = np.array(mgr.paraDomain.cellCenters())[:, :2]
+        model = np.array(mgr.model)
+        inside = np.array([_inside(p, g.polygon) for p in cells])
+        if inside.sum() >= 3:
+            rec_t, rec_bg = float(np.median(model[inside])), float(np.median(model[~inside]))
+            recovery = float(np.log(rec_t / rec_bg) / np.log(rho_t / rho_h)) if rho_t != rho_h else 0.0
+        else:
+            rec_t, rec_bg, recovery = None, float(np.median(model)), 0.0
+        # Recovered: the inverted contrast points the right way and reaches 20 % of the true contrast (log scale) or a
+        # factor of 1.5, whichever is smaller (a void's true contrast is huge; no inversion of surface data reaches it).
+        need = min(RECOVERY_THRESHOLD * abs(np.log(rho_t / rho_h)), np.log(RECOVERED_FACTOR))
+        recovered = bool(rec_t is not None and rho_t != rho_h and np.sign(np.log(rec_t / rec_bg)) == np.sign(np.log(rho_t / rho_h))
+                         and abs(np.log(rec_t / rec_bg)) >= need)
+        details.update(inverted=True, recovered_target=rec_t, recovered_background=rec_bg, recovery=recovery,
+                       recovered=recovered, chi2=float(mgr.inv.chi2()), inversion_cells=int(len(model)),
+                       section={"x": cells[:, 0].round(3).tolist(), "z": cells[:, 1].round(3).tolist(),
+                                "rho": np.round(model, 4).tolist()})
+        if not recovered and assessment.verdict != "not detectable":
+            assessment.verdict = "marginal"
+    details["seconds"] = round(time.time() - started, 1)
+
+    unit = "%"
+    asm = [
+        f"Signal-to-noise thresholds: >= {detect.CLEAR:g} clearly detectable, {detect.MARGINAL:g}-{detect.CLEAR:g} "
+        f"marginal, < {detect.MARGINAL:g} not detectable; S/N is the largest change in apparent resistivity over the "
+        f"data noise ({noise:g} %).",
+        f"{n} electrodes every {a:g} m ({L:g} m spread), {array} array, {scheme.size()} measurements.",
+        f"Host {rho_h:.3g} Ωm, target {rho_t:.3g} Ωm" + ("" if t.resistivity is not None or t.host_resistivity is not None
+                                                          else " (typical values; resistivity ranges over orders of magnitude, measure on site)") + ".",
+        "2D model: the target is infinitely long across the profile; homogeneous host, flat ground, electrodes on the "
+        "surface. Finite-element forward model (pyGIMLi); the target/host ratio cancels the mesh error.",
+    ]
+    if t.shape == "sphere":
+        asm.append("A sphere is modelled as a horizontal cylinder of the same diameter: a real 3D sphere gives a "
+                   "smaller anomaly than shown.")
+    if t.shape in ("prism", "vertical_cylinder"):
+        asm.append("A 3D block or shaft is modelled by its 2D cross-section; a short target gives a smaller anomaly.")
+    if details["inverted"]:
+        rt = details["recovered_target"]
+        asm.append(f"Inversion of the noisy data (smoothness constraint, λ 20, χ² {details['chi2']:.2g}): recovered "
+                   f"{'%.3g' % rt + ' Ωm in the target' if rt else 'no cells inside the target'} against "
+                   f"{details['recovered_background']:.3g} Ωm around it ({100 * details['recovery']:.0f} % of the true contrast "
+                   f"in log scale): " + ("recovered." if details["recovered"] else "not recovered (needs 20 % of the "
+                   "contrast in log scale or a factor of 1.5)."))
+    elif t.shape == "contact":
+        asm.append("Inversion not run for a contact (no closed target).")
+    if a > (t.size or a):
+        asm.append(f"Electrode spacing ({a:g} m) is larger than the target ({t.size:g} m): its shape is not resolved.")
+    if t.shape in ("horizontal_cylinder", "dyke", "contact"):
+        asm.append("2D target: infinitely long along strike, at right angles to the profile.")
+    assessment.assumptions = asm
+    assessment.units = unit
+    return {"method": "ert", "available": True, "contrast": float(rho_t / rho_h), "contrast_units": "resistivity ratio",
+            "instrument": f"{n} electrodes, {array}", "instrument_noise": float(noise), "field_noise": None,
+            "x": xs.round(4).tolist(), "anomaly": prof.tolist(), "assessment": assessment.to_dict(), "details": details}
+
+
+def _inside(p, poly) -> bool:
+    x, z = p
+    inside = False
+    j = len(poly) - 1
+    for i in range(len(poly)):
+        xi, zi = poly[i]
+        xj, zj = poly[j]
+        if (zi > z) != (zj > z) and x < (xj - xi) * (z - zi) / (zj - zi) + xi:
+            inside = not inside
+        j = i
+    return inside
+
+
+def remote(target: dict, survey: dict, url: str) -> dict:
+    """Ask an ERT service (another machine with pyGIMLi) for the result."""
+    req = urllib.request.Request(url, data=json.dumps({"target": target, "survey": survey}).encode(),
+                                 headers={"Content-Type": "application/json"})
+    timeout = float(os.environ.get("DETECTABILITY_ERT_TIMEOUT", DEFAULT_SERVICE_TIMEOUT))
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read())

{detectability-0.4.0 → detectability-0.5.0}/src/detectability/survey.py

@@ -13,14 +13,16 @@ from __future__ import annotations
 
 import datetime as _dt
 import json
+import re
 from dataclasses import asdict, dataclass, field, fields, replace
 
 import numpy as np
 
-from . import __version__, detect, gpr, gravity, igrf, magnetics, rocks
+from . import __version__, detect, ert, gpr, gravity, igrf, magnetics, rocks
 from .constants import SI_TO_UGAL
 
-METHODS = ("gravity", "magnetic", "gradient", "gpr")   # gradient: magnetic vertical gradient; gpr: ground-penetrating radar
+METHODS = ("gravity", "magnetic", "gradient", "gpr", "ert")   # gradient: magnetic vertical gradient; gpr: ground-penetrating
+# radar; ert: electrical resistivity tomography (needs pyGIMLi or an ERT service)
 DEFAULT_METHODS = ("gravity", "magnetic")
 
 SHAPES: dict[str, str] = {
@@ -54,6 +56,8 @@ class Target:
     conductivity: float | None = None              # mS/m, of the target (GPR)
     host_permittivity: float | None = None         # relative, of the host (GPR)
     host_conductivity: float | None = None         # mS/m, of the host (GPR)
+    resistivity: float | None = None               # ohm m, of the target (ERT); overrides the material table
+    host_resistivity: float | None = None          # ohm m, of the host (ERT)
 
     def validate(self) -> None:
         if self.shape not in SHAPES:
@@ -88,6 +92,11 @@ class Survey:
     date: str | None = None               # ISO date of the survey; default: today
     gpr_frequency: float | None = None    # MHz, antenna centre frequency; default: from the target depth
     gpr_system_performance: float = gpr.DEFAULT_SYSTEM_PERFORMANCE_DB   # dB, largest two-way loss the system records
+    ert_array: str = ert.DEFAULT_ARRAY    # dipole-dipole, wenner, schlumberger or gradient
+    ert_electrodes: int = ert.DEFAULT_ELECTRODES
+    ert_spacing: float | None = None      # m between electrodes; default: spread about six times the target depth
+    ert_noise: float = ert.DEFAULT_NOISE_PERCENT   # % of each apparent resistivity
+    ert_invert: bool = True               # also invert noisy synthetic data to see whether the target is recovered
     field_total: float | None = None      # nT; main field given directly instead of IGRF (all three together)
     field_inclination: float | None = None
     field_declination: float | None = None
@@ -157,10 +166,17 @@ class Report:
         if target.get("shape") != "dyke":
             target.pop("dip", None)
         survey = {k: v for k, v in self.survey.items() if v is not None}
+        for prefix, method in (("gpr_", "gpr"), ("ert_", "ert")):   # settings of methods not asked for add nothing
+            if method not in self.methods:
+                survey = {k: v for k, v in survey.items() if not k.startswith(prefix)}
+
+        def literal(d):  # JSON text, but Python booleans
+            return re.sub(r"(?<=: )(true|false)(?=,?\n)", lambda m: m.group(1).capitalize(),
+                          json.dumps(d, indent=4, ensure_ascii=False))
         return SCRIPT.format(
             version=self.version,
-            target=json.dumps(target, indent=4, ensure_ascii=False),
-            survey=json.dumps(survey, indent=4, ensure_ascii=False),
+            target=literal(target),
+            survey=literal(survey),
             methods=json.dumps(self.methods),
         )
 
@@ -379,6 +395,28 @@ def _gpr(t: Target, s: Survey, x) -> MethodResult:
                         assessment=a_, details=details)
 
 
+def _ert(t: Target, s: Survey) -> MethodResult:
+    """Electrical resistivity tomography: locally with pyGIMLi, else through DETECTABILITY_ERT_URL, else not available."""
+    import os
+    try:
+        if ert.available():
+            d = ert.run(t, s)
+        elif os.environ.get("DETECTABILITY_ERT_URL"):
+            try:
+                d = ert.remote(asdict(t), asdict(s), os.environ["DETECTABILITY_ERT_URL"])
+            except Exception as e:  # the service is down or too slow: say so instead of failing the whole report
+                return MethodResult("ert", False, f"the ERT service did not answer ({type(e).__name__}); try again later")
+            if not d.get("available", False):
+                return MethodResult("ert", False, d.get("reason", "the ERT service could not compute this target"))
+        else:
+            return MethodResult("ert", False, 'needs pyGIMLi: pip install "detectability[ert]"')
+    except KeyError as e:
+        return MethodResult("ert", False, str(e.args[0]) + " (give resistivity and host_resistivity directly)")
+    a = d.pop("assessment")
+    d["assessment"] = detect.Assessment(**a)
+    return MethodResult(**d)
+
+
 def evaluate(target, survey=None, methods=DEFAULT_METHODS) -> Report:
     """Model ``target`` (a ``Target`` or dict) for each method and assess it for ``survey`` (a ``Survey`` or dict)."""
     t, s = _as(Target, target), _as(Survey, survey)
@@ -396,6 +434,9 @@ def evaluate(target, survey=None, methods=DEFAULT_METHODS) -> Report:
         if method == "gpr":
             results.append(_gpr(t, s, x))
             continue
+        if method == "ert":
+            results.append(_ert(t, s))
+            continue
         contrast, units, problem = _contrast(t, method)
         if contrast is None:
             results.append(MethodResult(method, False, problem))

{detectability-0.4.0 → detectability-0.5.0}/src/detectability/validation.py

@@ -364,11 +364,42 @@ def cases() -> list[Case]:
                     "Ten materials, from dry sand to fresh water", "m/ns", 6.0,
                     float(np.max(np.abs(model_v - ref_v) / ref_v * 100.0))))
 
+    # --- ERT (finite elements, values stored by tools/ert_reference.py) ---------------------------------------------
+    out.extend(_ert_cases())
+
     # --- independent code ---------------------------------------------------------------------------------------
     out.extend(_harmonica_cases())
     return out
 
 
+ERT_FILE = "ert_reference.json"
+
+
+def ert_reference() -> dict | None:
+    """pyGIMLi forward-model values against analytic solutions, stored so the website needs no pyGIMLi."""
+    try:
+        return json.loads(resources.files("detectability").joinpath("data", ERT_FILE).read_text())
+    except FileNotFoundError:
+        return None
+
+
+def _ert_cases() -> list[Case]:
+    ref = ert_reference()
+    if not ref:
+        return []
+    w = ref["wenner_two_layer"]
+    v = ref["pygimli"]
+    return [
+        Case("ert-halfspace", "Analytical limit", "ERT, homogeneous ground", f"pyGIMLi {v} finite elements",
+             "Apparent resistivity equals the true resistivity", "100 Ωm, 48 electrodes, dipole-dipole, 1,035 data", "",
+             1.0, ref["halfspace_error_percent"]),
+        _profile_case("ert-wenner-two-layer", "Analytical limit", "ERT, two layers, Wenner sounding",
+                      f"pyGIMLi {v} finite elements", "Image-series solution for two layers",
+                      f"{w['rho1']:g} Ωm over {w['rho2']:g} Ωm, interface at {w['h']:g} m, a = 1–20 m", "Ωm", 2.0,
+                      np.array(w["spacing"]), np.array(w["model"]), np.array(w["analytic"])),
+    ]
+
+
 def harmonica_reference() -> dict | None:
     """The stored Harmonica values and the versions they were computed with (None if the file is missing)."""
     try:

{detectability-0.4.0 → detectability-0.5.0/src/detectability.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.4.0
+Version: 0.5.0
 Summary: Pre-survey detectability, modelled and reproducible: forward-modelled gravity and magnetic responses, station spacing and a detectability verdict for near-surface targets.
 Author: Mükremin Nergiz
 License-Expression: BSD-3-Clause
@@ -30,6 +30,8 @@ Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
 Provides-Extra: validation
 Requires-Dist: harmonica==0.7.0; extra == "validation"
+Provides-Extra: ert
+Requires-Dist: pygimli>=1.5; extra == "ert"
 Dynamic: license-file
 
 # Detectability
@@ -69,7 +71,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.4.0: sphere in limestone
+Detectability 0.5.0: sphere in limestone
 - gravity: peak 114 µGal, noise 11.2 µGal, S/N 10.2: clearly detectable
   stations every 5 m or less, profile at least 153 m long
 - magnetic: peak 0.462 nT, noise 2 nT, S/N 0.231: not detectable
@@ -87,10 +89,13 @@ Methods: `gravity`, `magnetic` (total-field anomaly) and, on request, `gradient`
 (lower minus upper sensor, in nT over the baseline), with presets for the Bartington Grad601, Sensys FGM650, Foerster
 FEREX 4.034 and GEM GSM-19G; and, on request, `gpr`: ground-penetrating radar, the echo of the target's top against
 the system's detection limit (radar range equation), with velocity, attenuation, antenna frequency, trace spacing and
-recording window. The defaults are `gravity` and `magnetic`:
+recording window; and, on request, `ert`: electrical resistivity tomography, a 2D finite-element model of the target
+under a line of electrodes (dipole-dipole, Wenner, Schlumberger or gradient array), the change it makes to the
+apparent resistivities, and whether an inversion of noisy synthetic data recovers it. ERT needs
+[pyGIMLi](https://www.pygimli.org): `pip install "detectability[ert]"`. The defaults are `gravity` and `magnetic`:
 
 ```python
-evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr", "ert"])
 ```
 
 ## Modules
@@ -101,6 +106,7 @@ evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
 | `gravity` | sphere, horizontal cylinder, right rectangular prism (Nagy; Plouff) and its gradient tensor, vertical cylinder (exact, by a rim integral) and its gradient tensor, vertical step, dyke, 2D polygon (Talwani; Won & Bevis) |
 | `magnetics` | total-field anomaly: sphere, horizontal cylinder, prism, vertical cylinder, 2D polygon, dyke (any dip), vertical contact; induced and remanent magnetisation (a gradiometer reading is the difference at two sensor heights) |
 | `gpr` | ground-penetrating radar: exact velocity and attenuation of a lossy medium, normal-incidence reflection coefficient, target-size factor (geometric optics, Rayleigh regime, Fresnel zone), echo against system performance; typical permittivity and conductivity (Davis & Annan 1989) |
+| `ert` | electrical resistivity tomography with pyGIMLi (optional): electrode layout, 2D finite-element forward model, inversion and recovery check; typical resistivities (Loke 1999, after Keller & Frischknecht 1966) |
 | `igrf` | IGRF-14 main field from location and date, from the official IAGA coefficients |
 | `rocks` | typical densities and magnetic susceptibilities with their ranges (Telford et al. 1990) |
 | `detect` | instrument presets with their sources (gravimeters, magnetometers, gradiometers), field noise, signal-to-noise ratio, verdict, station spacing, profile length |
@@ -145,6 +151,8 @@ python tools/harmonica_reference.py --check
 | Analytical limit | GPR, reflection coefficient | (√ε1 − √ε2)/(√ε1 + √ε2) for lossless media | 0.0e+00 % | 1.0e-10 % |
 | Analytical limit | GPR, very large sphere | Flat reflector at the same range | 5.0e-06 % | 1.0e-04 % |
 | Published values | GPR, velocity of common materials | Davis & Annan (1989) table velocities (rounded to 0.01 m/ns) | 4.92 % | 6 % |
+| Analytical limit | ERT, homogeneous ground | Apparent resistivity equals the true resistivity | 0.297 % | 1 % |
+| Analytical limit | ERT, two layers, Wenner sounding | Image-series solution for two layers | 0.144 % | 2 % |
 | Independent code | Prism, gravity | Harmonica 0.7.0 prism_gravity | 3.0e-12 % | 1.0e-08 % |
 | Independent code | Prism, magnetic | Harmonica 0.7.0 prism_magnetic | 4.8e-13 % | 1.0e-08 % |
 | Independent code | Sphere, gravity | Harmonica 0.7.0 point_gravity | 3.9e-14 % | 1.0e-10 % |
@@ -172,7 +180,7 @@ field noise (0.5 nT) is an assumption, not a published figure: soil, heading and
 
 See [CITATION.cff](https://github.com/mukremin-nergiz/detectability/blob/main/CITATION.cff), or:
 
-> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.4.0) [Computer software].
+> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.5.0) [Computer software].
 > Zenodo. https://doi.org/10.5281/zenodo.23931815
 
 The DOI above always resolves to the latest version; each release also has its own DOI on Zenodo. Changes between

{detectability-0.4.0 → detectability-0.5.0}/src/detectability.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/detectability/__init__.py
 src/detectability/constants.py
 src/detectability/detect.py
+src/detectability/ert.py
 src/detectability/gpr.py
 src/detectability/gravity.py
 src/detectability/igrf.py
@@ -16,9 +17,12 @@ src/detectability.egg-info/SOURCES.txt
 src/detectability.egg-info/dependency_links.txt
 src/detectability.egg-info/requires.txt
 src/detectability.egg-info/top_level.txt
+src/detectability/data/ert_reference.json
 src/detectability/data/harmonica_reference.json
 src/detectability/data/igrf14coeffs.txt
 tests/test_detect.py
+tests/test_ert.py
+tests/test_ert_pygimli.py
 tests/test_gpr.py
 tests/test_gravity.py
 tests/test_igrf.py

{detectability-0.4.0 → detectability-0.5.0}/src/detectability.egg-info/requires.txt

@@ -1,5 +1,8 @@
 numpy>=1.24
 
+[ert]
+pygimli>=1.5
+
 [test]
 pytest>=7
 

detectability-0.5.0/tests/test_ert.py

@@ -0,0 +1,61 @@
+import json
+
+import numpy as np
+import pytest
+
+from detectability import ert, evaluate, validation
+from detectability.survey import Target
+
+TUNNEL = {"shape": "horizontal_cylinder", "depth_top": 3, "size": 2, "material": "air", "host": "limestone"}
+
+
+def test_typical_resistivity_is_inside_the_published_range():
+    for name, (typ, lo, hi) in ert.RESISTIVITY.items():
+        assert lo <= typ <= hi, name
+    assert ert.resistivity("limestone") == pytest.approx(np.sqrt(50 * 400), rel=0.01)
+
+
+def test_geometry_outlines():
+    g = ert.geometry(Target(**TUNNEL))
+    assert g.depth_needed == 5 and g.area == pytest.approx(np.pi)
+    d = ert.geometry(Target(shape="dyke", depth_top=1, depth_bottom=11, size=2, dip=45))
+    assert d.polygon[2][0] == pytest.approx(1 + 10)  # bottom shifted by the dip
+    assert ert.default_spacing(5, 48) == 0.5
+
+
+def test_unavailable_without_pygimli_or_service(monkeypatch):
+    monkeypatch.setattr(ert, "available", lambda: False)
+    monkeypatch.delenv("DETECTABILITY_ERT_URL", raising=False)
+    r = evaluate(TUNNEL, {}, methods=["ert"]).result("ert")
+    assert not r.available and "pygimli" in r.reason.lower()
+
+
+def test_remote_service_result_and_failure(monkeypatch):
+    monkeypatch.setattr(ert, "available", lambda: False)
+    monkeypatch.setenv("DETECTABILITY_ERT_URL", "http://127.0.0.1:9/evaluate")
+    fake = {"method": "ert", "available": True, "contrast": 7000.0, "contrast_units": "resistivity ratio",
+            "instrument": "48 electrodes, dipole-dipole", "instrument_noise": 3.0, "field_noise": None,
+            "x": [-1.0, 0.0, 1.0], "anomaly": [1.0, 10.0, 1.0], "details": {"recovered": True},
+            "assessment": {"method": "ert", "peak": 10.0, "peak_at": 0.0, "width": 1.0, "shape": "bell", "noise": 3.0,
+                           "snr": 3.3, "verdict": "marginal", "station_spacing": 0.5, "profile_length": 23.5,
+                           "assumptions": ["x"], "units": "%"}}
+    monkeypatch.setattr(ert, "remote", lambda t, s, url: json.loads(json.dumps(fake)))
+    rep = evaluate(TUNNEL, {}, methods=["ert"])
+    assert rep.result("ert").assessment.verdict == "marginal" and rep.recommended == "ert"
+
+    def down(t, s, url):
+        raise TimeoutError
+    monkeypatch.setattr(ert, "remote", down)
+    r = evaluate(TUNNEL, {}, methods=["ert"]).result("ert")
+    assert not r.available and "did not answer" in r.reason
+
+
+def test_script_has_python_booleans_and_only_asked_settings():
+    rep = evaluate(TUNNEL, {"ert_invert": False}, methods=["gravity"])
+    s = rep.script()
+    assert "ert_" not in s and "gpr_" not in s and "true" not in s
+
+
+def test_stored_validation_rows_pass():
+    rows = [c for c in validation.cases() if c.key.startswith("ert-")]
+    assert len(rows) == 2 and all(c.passed for c in rows)

detectability-0.5.0/tests/test_ert_pygimli.py

@@ -0,0 +1,19 @@
+import pytest
+
+from detectability import evaluate
+
+TUNNEL = {"shape": "horizontal_cylinder", "depth_top": 3, "size": 2, "material": "air", "host": "limestone"}
+
+pg = pytest.importorskip("pygimli")
+
+
+def test_ert_with_pygimli_tunnel_in_limestone():
+    r = evaluate(TUNNEL, {"ert_invert": False}, methods=["ert"]).result("ert")
+    assert r.available and 5 < r.details["max_anomaly_percent"] < 20
+    assert r.assessment.station_spacing == 0.5
+
+
+def test_conductive_dyke_is_clear():
+    r = evaluate({"shape": "dyke", "depth_top": 1, "depth_bottom": 10, "size": 2, "material": "clay",
+                  "host": "granite"}, {"ert_invert": False}, methods=["ert"]).result("ert")
+    assert r.assessment.verdict == "clearly detectable"