detectability 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.3.0
+Version: 0.4.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
@@ -34,9 +34,9 @@ Dynamic: license-file
 
 # Detectability
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23931815.svg)](https://doi.org/10.5281/zenodo.23931815)
 [![tests](https://github.com/mukremin-nergiz/detectability/actions/workflows/tests.yml/badge.svg)](https://github.com/mukremin-nergiz/detectability/actions/workflows/tests.yml)
 [![licence: BSD-3-Clause](https://img.shields.io/badge/licence-BSD--3--Clause-blue.svg)](https://github.com/mukremin-nergiz/detectability/blob/main/LICENSE)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23931815.svg)](https://doi.org/10.5281/zenodo.23931815)
 
 **Pre-survey detectability, modelled and reproducible.** Describe a buried target and a survey. Detectability models the gravity and
 magnetic response of the target, compares it with instrument and field noise, and gives a verdict for each method
@@ -69,7 +69,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.3.0: sphere in limestone
+Detectability 0.4.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
@@ -85,10 +85,12 @@ in, and measured contrasts can be given instead.
 
 Methods: `gravity`, `magnetic` (total-field anomaly) and, on request, `gradient`: the reading of a vertical gradiometer
 (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. The defaults are `gravity` and `magnetic`:
+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`:
 
 ```python
-evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
 ```
 
 ## Modules
@@ -98,6 +100,7 @@ evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
 | `survey` | `evaluate()`: target and survey in, report and reproduction script out |
 | `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) |
 | `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 |
@@ -137,6 +140,11 @@ python tools/harmonica_reference.py --check
 | Poisson's relation | Dipping dyke (60°), gravity ↔ magnetic | Vertical derivative of the gravity dyke | 2.6e-08 % | 1.0e-04 % |
 | Poisson's relation | Vertical cylinder, gravity ↔ magnetic | Vertical derivative of the gravity cylinder | 3.6e-08 % | 1.0e-04 % |
 | Poisson's relation | Vertical contact, gravity ↔ magnetic | Vertical derivative of the gravity step | 3.9e-06 % | 1.0e-04 % |
+| Analytical limit | GPR, attenuation in a low-loss host | Low-loss limit 1636 σ/√εr dB/m (σ in S/m) | 1.1e-04 % | 0.01 % |
+| Analytical limit | GPR, velocity in a low-loss host | c/√εr | 2.5e-06 % | 1.0e-04 % |
+| 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 % |
 | 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 % |
@@ -164,7 +172,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.3.0) [Computer software].
+> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.4.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.3.0 → detectability-0.4.0}/README.md

@@ -1,8 +1,8 @@
 # Detectability
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23931815.svg)](https://doi.org/10.5281/zenodo.23931815)
 [![tests](https://github.com/mukremin-nergiz/detectability/actions/workflows/tests.yml/badge.svg)](https://github.com/mukremin-nergiz/detectability/actions/workflows/tests.yml)
 [![licence: BSD-3-Clause](https://img.shields.io/badge/licence-BSD--3--Clause-blue.svg)](https://github.com/mukremin-nergiz/detectability/blob/main/LICENSE)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23931815.svg)](https://doi.org/10.5281/zenodo.23931815)
 
 **Pre-survey detectability, modelled and reproducible.** Describe a buried target and a survey. Detectability models the gravity and
 magnetic response of the target, compares it with instrument and field noise, and gives a verdict for each method
@@ -35,7 +35,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.3.0: sphere in limestone
+Detectability 0.4.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
@@ -51,10 +51,12 @@ in, and measured contrasts can be given instead.
 
 Methods: `gravity`, `magnetic` (total-field anomaly) and, on request, `gradient`: the reading of a vertical gradiometer
 (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. The defaults are `gravity` and `magnetic`:
+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`:
 
 ```python
-evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
 ```
 
 ## Modules
@@ -64,6 +66,7 @@ evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
 | `survey` | `evaluate()`: target and survey in, report and reproduction script out |
 | `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) |
 | `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 |
@@ -103,6 +106,11 @@ python tools/harmonica_reference.py --check
 | Poisson's relation | Dipping dyke (60°), gravity ↔ magnetic | Vertical derivative of the gravity dyke | 2.6e-08 % | 1.0e-04 % |
 | Poisson's relation | Vertical cylinder, gravity ↔ magnetic | Vertical derivative of the gravity cylinder | 3.6e-08 % | 1.0e-04 % |
 | Poisson's relation | Vertical contact, gravity ↔ magnetic | Vertical derivative of the gravity step | 3.9e-06 % | 1.0e-04 % |
+| Analytical limit | GPR, attenuation in a low-loss host | Low-loss limit 1636 σ/√εr dB/m (σ in S/m) | 1.1e-04 % | 0.01 % |
+| Analytical limit | GPR, velocity in a low-loss host | c/√εr | 2.5e-06 % | 1.0e-04 % |
+| 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 % |
 | 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 % |
@@ -130,7 +138,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.3.0) [Computer software].
+> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.4.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.3.0 → detectability-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "detectability"
-version = "0.3.0"
+version = "0.4.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"]

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

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

{detectability-0.3.0 → detectability-0.4.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"}
+UNITS = {"gravity": "µGal", "magnetic": "nT", "gradient": "nT", "gpr": "× detection limit"}
 
 
 def effective_noise(instrument: float, field_noise: float) -> float:

detectability-0.4.0/src/detectability/gpr.py

@@ -0,0 +1,176 @@
+"""Ground-penetrating radar (GPR): wave speed and attenuation in the ground, reflection at the target, and the echo of
+a buried target compared with what the radar system can still detect.
+
+The model is a radar range (loss budget) calculation, in the spirit of GPR survey-design practice (Annan & Cosway 1992,
+"Ground penetrating radar survey design", SAGEEP '92, 329-351; Annan 2009, "Electromagnetic principles of ground
+penetrating radar", in Jol (ed.), Ground Penetrating Radar: Theory and Applications, Elsevier):
+
+    echo amplitude (relative to the amplitude 1 m from the antenna) = |R| * S * exp(-2 alpha r) * 1 m / (2 r)
+
+with R the normal-incidence reflection coefficient between host and target, S the target-size factor (1 for a large
+flat reflector), alpha the attenuation of the host and r the range from the antenna to the reflecting surface. The echo is
+detectable while its loss stays within the system performance Q (dB, the largest two-way loss the system can still
+record, referred to 1 m). Signal-to-noise ratio = echo / 10**(-Q/20).
+
+Each step and its limits:
+- Wave speed and attenuation are exact for a homogeneous medium with frequency-independent permittivity and
+  conductivity. Real soils lose more at high frequency (water relaxation, scattering), so results above ~500 MHz in
+  wet or clayey ground are optimistic.
+- R is exact for a plane wave at normal incidence on a plane boundary; a perfect conductor (metal) has R = -1.
+- S is geometric optics for curved targets: a sphere of radius a at range r returns a / (r + a) of a flat reflector's
+  echo and a horizontal cylinder sqrt(a / (r + a)) (one curved direction). Where the target is small compared with the
+  wavelength (k a < 1, k = 2 pi / lambda) the echo falls in the Rayleigh regime as (k a)**2 (sphere) and (k a)**1.5
+  (cylinder), joined continuously at k a = 1. Flat tops smaller than the first Fresnel zone (radius sqrt(lambda r / 2))
+  return the fraction of the zone they cover. Antenna gain, beam pattern, coupling and surface clutter are in Q.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+C0 = 299_792_458.0            # speed of light in vacuum, m/s
+EPS0 = 8.8541878128e-12       # vacuum permittivity, F/m (CODATA 2018)
+MU0 = 1.25663706212e-6        # vacuum permeability, H/m (CODATA 2018)
+NEPER_TO_DB = 20.0 / np.log(10.0)
+
+# Typical relative permittivity and conductivity (mS/m), each as (typical, low, high). Ranges from the table of
+# Davis & Annan (1989, Geophysical Prospecting 37, 531-551), as reproduced in USACE EM 1110-1-1802 (1995) Table 4-3;
+# "typical" is the middle of the permittivity range and the geometric middle of the conductivity range. The same table
+# gives velocity and attenuation, which the tests check against these values. Verify against the source before release.
+PERMITTIVITY: dict[str, tuple[float, float, float]] = {
+    "air": (1.0, 1.0, 1.0),
+    "distilled water": (80.0, 80.0, 80.0),
+    "fresh water": (80.0, 80.0, 80.0),
+    "sea water": (80.0, 80.0, 80.0),
+    "dry sand": (4.0, 3.0, 5.0),
+    "wet sand": (25.0, 20.0, 30.0),
+    "limestone": (6.0, 4.0, 8.0),
+    "shale": (10.0, 5.0, 15.0),
+    "silt": (17.5, 5.0, 30.0),
+    "clay": (22.5, 5.0, 40.0),
+    "granite": (5.0, 4.0, 6.0),
+    "rock salt": (5.5, 5.0, 6.0),
+    "ice": (3.5, 3.0, 4.0),
+}
+CONDUCTIVITY_MS_M: dict[str, tuple[float, float, float]] = {
+    "air": (0.0, 0.0, 0.0),
+    "distilled water": (0.01, 0.01, 0.01),
+    "fresh water": (0.5, 0.5, 0.5),
+    "sea water": (3000.0, 3000.0, 3000.0),
+    "dry sand": (0.01, 0.01, 0.01),
+    "wet sand": (0.3, 0.1, 1.0),
+    "limestone": (1.0, 0.5, 2.0),
+    "shale": (10.0, 1.0, 100.0),
+    "silt": (10.0, 1.0, 100.0),
+    "clay": (45.0, 2.0, 1000.0),
+    "granite": (0.1, 0.01, 1.0),
+    "rock salt": (0.1, 0.01, 1.0),
+    "ice": (0.01, 0.01, 0.01),
+}
+METALS = {"metal"}  # perfect conductors: R = -1 whatever the host
+
+# Antenna centre frequency for a target depth (Annan 2001, as given by Robinson et al. 2013, Table 2 in USEPA CLU-IN
+# "Ground Penetrating Radar"): a rule of thumb that keeps the resolution near a quarter of the depth.
+DEPTH_TO_FREQUENCY_MHZ = ((0.5, 1000.0), (1.0, 500.0), (2.0, 200.0), (5.0, 100.0), (10.0, 50.0), (30.0, 25.0),
+                          (50.0, 10.0))
+ANTENNAS_MHZ = (10.0, 25.0, 50.0, 100.0, 200.0, 250.0, 400.0, 500.0, 800.0, 1000.0, 1600.0)
+
+DEFAULT_SYSTEM_PERFORMANCE_DB = 100.0  # typical dynamic range 90-130 dB (Benson et al. 1984; USACE 1995)
+
+
+@dataclass(frozen=True)
+class Medium:
+    permittivity: float       # relative
+    conductivity: float       # S/m
+
+    def wavenumber(self, f: float) -> complex:
+        """Complex wavenumber beta - i alpha at frequency f (Hz)."""
+        w = 2 * np.pi * f
+        eps = self.permittivity * EPS0 - 1j * self.conductivity / w
+        k = w * np.sqrt(MU0 * eps + 0j)
+        return complex(k.real, -abs(k.imag))
+
+    def velocity(self, f: float) -> float:
+        """Phase velocity, m/s."""
+        return 2 * np.pi * f / self.wavenumber(f).real
+
+    def attenuation_db(self, f: float) -> float:
+        """Amplitude attenuation, dB per metre (one way)."""
+        return -self.wavenumber(f).imag * NEPER_TO_DB
+
+    def impedance(self, f: float) -> complex:
+        w = 2 * np.pi * f
+        return np.sqrt(MU0 / (self.permittivity * EPS0 - 1j * self.conductivity / w) + 0j)
+
+    def wavelength(self, f: float) -> float:
+        return self.velocity(f) / f
+
+
+def medium(name: str) -> Medium:
+    try:
+        return Medium(PERMITTIVITY[name][0], CONDUCTIVITY_MS_M[name][0] / 1000.0)
+    except KeyError:
+        raise KeyError(f"no GPR properties for {name!r}; known: {', '.join(sorted(set(PERMITTIVITY) | METALS))}") from None
+
+
+def low_loss_attenuation_db(permittivity: float, conductivity: float) -> float:
+    """High-frequency (low-loss) limit of the attenuation, dB/m: 1636 sigma / sqrt(eps_r) with sigma in S/m."""
+    return NEPER_TO_DB * conductivity / 2 * np.sqrt(MU0 / EPS0) / np.sqrt(permittivity)
+
+
+def reflection(host: Medium, target: Medium | None, f: float) -> complex:
+    """Normal-incidence reflection coefficient from ``host`` onto ``target`` (None: perfect conductor, R = -1)."""
+    if target is None:
+        return complex(-1.0)
+    z1, z2 = host.impedance(f), target.impedance(f)
+    return complex((z2 - z1) / (z2 + z1))
+
+
+def fresnel_radius(wavelength: float, r: np.ndarray) -> np.ndarray:
+    """Radius of the first Fresnel zone on a reflector at range r (two-way path), m."""
+    return np.sqrt(wavelength * r / 2 + wavelength**2 / 16)
+
+
+def size_factor(kind: str, r: np.ndarray, wavelength: float, a: float = 0.0, width: float = 0.0,
+                length: float = 0.0) -> np.ndarray:
+    """Echo of the target relative to an infinite flat reflector at the same range (see the module notes).
+
+    kind: "sphere" (radius a), "cylinder" (horizontal, radius a), "disc" (flat top of radius a), "strip" (flat top of
+    width ``width``, long along strike), "rectangle" (flat top ``width`` x ``length``), "plane" (infinite).
+    """
+    r = np.asarray(r, float)
+    ka = 2 * np.pi * a / wavelength
+    if kind == "sphere":
+        return a / (r + a) * min(1.0, ka) ** 2
+    if kind == "cylinder":
+        return np.sqrt(a / (r + a)) * min(1.0, ka) ** 1.5
+    rf = fresnel_radius(wavelength, r)
+    if kind == "disc":
+        return np.minimum(1.0, (a / rf) ** 2)
+    if kind == "strip":
+        return np.minimum(1.0, width / (2 * rf))
+    if kind == "rectangle":
+        return np.minimum(1.0, width * length / (np.pi * rf**2))
+    if kind == "plane":
+        return np.ones_like(r)
+    raise ValueError(f"unknown target kind {kind!r}")
+
+
+def echo(r: np.ndarray, host: Medium, R: complex, factor: np.ndarray, f: float) -> np.ndarray:
+    """Echo amplitude relative to the amplitude 1 m from the antenna, for reflecting surfaces at ranges r (m)."""
+    r = np.maximum(np.asarray(r, float), 1e-3)
+    alpha = host.attenuation_db(f) / NEPER_TO_DB
+    return abs(R) * factor * np.exp(-2 * alpha * r) / (2 * r)
+
+
+def frequency_for_depth(depth: float) -> float:
+    """Antenna centre frequency (MHz) for a target depth, from the depth-frequency rule, snapped to a common antenna."""
+    d, fr = np.array(DEPTH_TO_FREQUENCY_MHZ).T
+    f = float(np.exp(np.interp(np.log(max(depth, 1e-3)), np.log(d), np.log(fr))))
+    return min(ANTENNAS_MHZ, key=lambda a: abs(np.log(a / f)))
+
+
+def two_way_time_ns(depth: float, velocity: float) -> float:
+    return 2 * depth / velocity * 1e9

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

@@ -17,10 +17,10 @@ from dataclasses import asdict, dataclass, field, fields, replace
 
 import numpy as np
 
-from . import __version__, detect, gravity, igrf, magnetics, rocks
+from . import __version__, detect, gpr, gravity, igrf, magnetics, rocks
 from .constants import SI_TO_UGAL
 
-METHODS = ("gravity", "magnetic", "gradient")   # gradient: magnetic vertical gradient (two-sensor gradiometer)
+METHODS = ("gravity", "magnetic", "gradient", "gpr")   # gradient: magnetic vertical gradient; gpr: ground-penetrating radar
 DEFAULT_METHODS = ("gravity", "magnetic")
 
 SHAPES: dict[str, str] = {
@@ -50,6 +50,10 @@ class Target:
     host: str = "limestone"               # surrounding material
     density_contrast: float | None = None          # kg/m^3, overrides the material tables
     susceptibility_contrast: float | None = None   # SI, overrides the material tables
+    permittivity: float | None = None              # relative, of the target (GPR); overrides the material table
+    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)
 
     def validate(self) -> None:
         if self.shape not in SHAPES:
@@ -82,6 +86,8 @@ class Survey:
     latitude: float | None = None         # for the main field (IGRF-14); needed for magnetics
     longitude: float | None = None
     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
     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
@@ -101,6 +107,7 @@ class MethodResult:
     x: list[float] = field(default_factory=list)
     anomaly: list[float] = field(default_factory=list)
     assessment: detect.Assessment | None = None
+    details: dict | None = None           # method-specific figures (GPR: frequency, velocity, attenuation, ...)
 
 
 @dataclass
@@ -129,8 +136,14 @@ class Report:
                 lines.append(f"- {r.method}: not assessed ({r.reason})")
                 continue
             a = r.assessment
-            lines.append(f"- {r.method}: peak {a.peak:.3g} {a.units}, noise {a.noise:.3g} {a.units}, "
-                         f"S/N {a.snr:.3g}: {a.verdict}")
+            if r.method == "gpr":
+                d = r.details
+                margin = 20 * np.log10(a.snr) if a.snr > 0 else float("-inf")
+                lines.append(f"- gpr ({d['frequency_mhz']:g} MHz): echo {margin:+.1f} dB against the detection limit, "
+                             f"S/N {a.snr:.3g}: {a.verdict}")
+            else:
+                lines.append(f"- {r.method}: peak {a.peak:.3g} {a.units}, noise {a.noise:.3g} {a.units}, "
+                             f"S/N {a.snr:.3g}: {a.verdict}")
             if a.verdict != "not detectable":
                 lines.append(f"  stations every {a.station_spacing:g} m or less, profile at least "
                              f"{a.profile_length:.0f} m long")
@@ -273,6 +286,99 @@ def _gradient(t: Target, x, chi, amb, s: Survey, baseline: float):
     return _magnetic(t, x, chi, amb, low) - _magnetic(t, x, chi, amb, high)
 
 
+def _gpr_medium(name: str, permittivity, conductivity):
+    """Medium from given properties or the GPR table; None for a metal (perfect conductor)."""
+    if permittivity is not None:
+        return gpr.Medium(permittivity, (conductivity or 0.0) / 1000.0)
+    if name in gpr.METALS:
+        return None
+    m = gpr.medium(name)
+    return m if conductivity is None else gpr.Medium(m.permittivity, conductivity / 1000.0)
+
+
+def _gpr(t: Target, s: Survey, x) -> MethodResult:
+    """Ground-penetrating radar: echo of the target's top surface against the system's detection limit."""
+    if t.shape == "contact":
+        return MethodResult("gpr", False, "a vertical contact has no horizontal surface to reflect the radar wave; "
+                            "GPR sees it only as a diffraction at its top edge, which is not modelled")
+    if t.depth_top <= 0:
+        return MethodResult("gpr", False, "GPR needs the target below the surface (depth_top > 0)")
+    try:
+        if t.host in gpr.METALS:
+            raise KeyError(f"the host cannot be a metal for GPR")
+        host = _gpr_medium(t.host, t.host_permittivity, t.host_conductivity)
+        target = _gpr_medium(t.material, t.permittivity, t.conductivity)
+    except KeyError as e:
+        return MethodResult("gpr", False, str(e.args[0]) + " (give permittivity and conductivity directly)")
+    if s.gpr_system_performance <= 0 or (s.gpr_frequency is not None and s.gpr_frequency <= 0):
+        raise ValueError("gpr_frequency and gpr_system_performance must be positive")
+
+    f_mhz = s.gpr_frequency or gpr.frequency_for_depth(t.depth_top)
+    f = f_mhz * 1e6
+    R = gpr.reflection(host, target, f)
+    lam = host.wavelength(f)
+    v = host.velocity(f)
+    a = (t.size or 0) / 2
+    if t.shape in ("sphere", "horizontal_cylinder"):
+        centre = t.depth_top + a
+        r = np.hypot(x, centre) - a
+        factor = gpr.size_factor("sphere" if t.shape == "sphere" else "cylinder", r, lam, a=a)
+    else:
+        r = np.hypot(x, t.depth_top)
+        if t.shape == "vertical_cylinder":
+            factor = gpr.size_factor("disc", r, lam, a=a)
+        elif t.shape == "prism":
+            factor = gpr.size_factor("rectangle", r, lam, width=t.size, length=t.length or t.size)
+        else:
+            factor = gpr.size_factor("strip", r, lam, width=t.size)
+    amplitude = gpr.echo(r, host, R, factor, f)
+    floor = 10 ** (-s.gpr_system_performance / 20)
+    snr_profile = amplitude / floor
+    a_ = detect.assess(x, snr_profile, 1.0, depth=t.depth_top, method="gpr")
+    nyquist = lam / 4
+    a_.station_spacing = detect._nice(min(a_.width / detect.STATIONS_ACROSS, nyquist))
+    t0 = gpr.two_way_time_ns(t.depth_top, v)
+    window = 1.3 * gpr.two_way_time_ns(max(t.depth_top + (t.size or 0), t.depth_top), v)
+    alpha = float(host.attenuation_db(f))
+    k_a = 2 * np.pi * a / lam
+    a_.assumptions = [
+        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 echo over the system's detection limit.",
+        f"System performance {s.gpr_system_performance:g} dB (largest two-way loss recorded, referred to 1 m; "
+        "typical systems 90-130 dB). It includes antenna gain and coupling; clutter and noise at the site lower it.",
+        f"Antenna {f_mhz:g} MHz" + ("" if s.gpr_frequency else " (chosen from the target depth)") +
+        f"; host: relative permittivity {host.permittivity:g}, conductivity {host.conductivity * 1000:g} mS/m, "
+        f"velocity {v / 1e9:.3g} m/ns, attenuation {alpha:.3g} dB/m (one way).",
+        "Reflection coefficient " + ("-1 (metal)" if target is None else f"{abs(R):.3g} (normal incidence, "
+                                     f"target permittivity {target.permittivity:g}, conductivity "
+                                     f"{target.conductivity * 1000:g} mS/m)") + ".",
+        "Homogeneous host with frequency-independent properties; real soils lose more at high frequency, so wet or "
+        "clayey ground above ~500 MHz is optimistic.",
+        f"Trace spacing at most a quarter wavelength in the host ({nyquist:.3g} m) and {detect.STATIONS_ACROSS} traces "
+        "across the echo.",
+        f"Two-way time to the target top {t0:.3g} ns; record at least {window:.3g} ns (30 % margin).",
+    ]
+    if t.shape in ("sphere", "horizontal_cylinder"):
+        a_.assumptions.append("Curved target: geometric optics" + (f"; small against the wavelength (k a = {k_a:.2g}), "
+                              "Rayleigh scaling applied" if k_a < 1 else "") + ".")
+    else:
+        a_.assumptions.append("Echo of the flat top surface; a top smaller than the first Fresnel zone returns the "
+                              "fraction of the zone it covers.")
+    if (t.size or 0) < nyquist:
+        a_.assumptions.append(f"The target ({t.size:g} m) is smaller than the vertical resolution (a quarter "
+                              f"wavelength, {nyquist:.3g} m): it shows as a diffraction hyperbola, its size is not resolved.")
+    if t.shape in TWO_D:
+        a_.assumptions.append("2D target: infinitely long along strike, at right angles to the profile.")
+    details = {"frequency_mhz": float(f_mhz), "velocity_m_per_ns": float(v / 1e9), "attenuation_db_per_m": alpha,
+               "wavelength_m": float(lam), "reflection_coefficient": float(abs(R)), "two_way_time_ns": float(t0),
+               "time_window_ns": float(window), "vertical_resolution_m": float(nyquist),
+               "margin_db": float(20 * np.log10(a_.snr)) if a_.snr > 0 else None,
+               "system_performance_db": s.gpr_system_performance}
+    return MethodResult("gpr", True, contrast=abs(R), contrast_units="reflection coefficient",
+                        instrument=f"{f_mhz:g} MHz antenna", x=x.round(4).tolist(), anomaly=snr_profile.tolist(),
+                        assessment=a_, details=details)
+
+
 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)
@@ -287,6 +393,9 @@ def evaluate(target, survey=None, methods=DEFAULT_METHODS) -> Report:
     x = _profile(t)
     results = []
     for method in methods:
+        if method == "gpr":
+            results.append(_gpr(t, s, x))
+            continue
         contrast, units, problem = _contrast(t, method)
         if contrast is None:
             results.append(MethodResult(method, False, problem))

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

@@ -18,7 +18,7 @@ from importlib import resources
 
 import numpy as np
 
-from . import gravity, igrf, magnetics
+from . import gpr, gravity, igrf, magnetics
 from .constants import G, SI_TO_UGAL
 from .magnetics import MU0, Ambient
 
@@ -330,6 +330,40 @@ def cases() -> list[Case]:
         magnetics.contact(x, 5.0, 40.0, CHI, POLE),
         _poisson(_dgz_dz(lambda a, b: gravity.vertical_step(x, a, b, 1000.0), 5.0, 40.0), CHI, POLE, 1000.0)))
 
+    # --- ground-penetrating radar --------------------------------------------------------------------------------
+    lime = gpr.medium("limestone")
+    out.append(Case("gpr-low-loss", "Analytical limit", "GPR, attenuation in a low-loss host",
+                    "Exact complex wavenumber", "Low-loss limit 1636 σ/√εr dB/m (σ in S/m)", "Limestone (εr 6, 1 mS/m), 1 GHz",
+                    "dB/m", 0.01, _value_error(lime.attenuation_db(1e9),
+                                               gpr.low_loss_attenuation_db(lime.permittivity, lime.conductivity))))
+    sand = gpr.medium("dry sand")
+    out.append(Case("gpr-velocity", "Analytical limit", "GPR, velocity in a low-loss host", "Exact complex wavenumber",
+                    "c/√εr", "Dry sand (εr 4, 0.01 mS/m), 100 MHz", "m/ns", 1e-4,
+                    _value_error(sand.velocity(1e8), gpr.C0 / np.sqrt(sand.permittivity))))
+    air = gpr.Medium(1.0, 0.0)
+    dry_lime = gpr.Medium(lime.permittivity, 0.0)
+    out.append(Case("gpr-reflection", "Analytical limit", "GPR, reflection coefficient", "Ratio of complex impedances",
+                    "(√ε1 − √ε2)/(√ε1 + √ε2) for lossless media", "Air void in limestone (εr 6 and 1)", "", 1e-10,
+                    _value_error(abs(gpr.reflection(dry_lime, air, 1e8)),
+                                 (np.sqrt(6.0) - 1.0) / (np.sqrt(6.0) + 1.0))))
+    r = np.linspace(1.0, 50.0, 50)
+    out.append(Case(
+        "gpr-sphere-plane", "Analytical limit", "GPR, very large sphere", "Geometric optics (convex mirror)",
+        "Flat reflector at the same range", "Radius 10⁹ m, ranges 1–50 m, 100 MHz in limestone", "", 1e-4,
+        _profile_error(gpr.size_factor("sphere", r, lime.wavelength(1e8), a=1e9),
+                       gpr.size_factor("plane", r, lime.wavelength(1e8)))))
+    # Davis & Annan (1989) table, as reproduced in USACE EM 1110-1-1802 (1995) Table 4-3: velocity in m/ns.
+    table_v = {"dry sand": 0.15, "wet sand": 0.06, "limestone": 0.12, "shale": 0.09, "silt": 0.07, "clay": 0.06,
+               "granite": 0.13, "rock salt": 0.13, "ice": 0.16, "fresh water": 0.033}
+    names = list(table_v)
+    model_v = np.array([gpr.medium(n).velocity(1e8) / 1e9 for n in names])
+    ref_v = np.array([table_v[n] for n in names])
+    out.append(Case("gpr-table-velocity", "Published values", "GPR, velocity of common materials",
+                    "Exact velocity from the typical εr and σ, 100 MHz",
+                    "Davis & Annan (1989) table velocities (rounded to 0.01 m/ns)",
+                    "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))))
+
     # --- independent code ---------------------------------------------------------------------------------------
     out.extend(_harmonica_cases())
     return out

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.3.0
+Version: 0.4.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
@@ -34,9 +34,9 @@ Dynamic: license-file
 
 # Detectability
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23931815.svg)](https://doi.org/10.5281/zenodo.23931815)
 [![tests](https://github.com/mukremin-nergiz/detectability/actions/workflows/tests.yml/badge.svg)](https://github.com/mukremin-nergiz/detectability/actions/workflows/tests.yml)
 [![licence: BSD-3-Clause](https://img.shields.io/badge/licence-BSD--3--Clause-blue.svg)](https://github.com/mukremin-nergiz/detectability/blob/main/LICENSE)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23931815.svg)](https://doi.org/10.5281/zenodo.23931815)
 
 **Pre-survey detectability, modelled and reproducible.** Describe a buried target and a survey. Detectability models the gravity and
 magnetic response of the target, compares it with instrument and field noise, and gives a verdict for each method
@@ -69,7 +69,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.3.0: sphere in limestone
+Detectability 0.4.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
@@ -85,10 +85,12 @@ in, and measured contrasts can be given instead.
 
 Methods: `gravity`, `magnetic` (total-field anomaly) and, on request, `gradient`: the reading of a vertical gradiometer
 (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. The defaults are `gravity` and `magnetic`:
+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`:
 
 ```python
-evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient", "gpr"])
 ```
 
 ## Modules
@@ -98,6 +100,7 @@ evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
 | `survey` | `evaluate()`: target and survey in, report and reproduction script out |
 | `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) |
 | `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 |
@@ -137,6 +140,11 @@ python tools/harmonica_reference.py --check
 | Poisson's relation | Dipping dyke (60°), gravity ↔ magnetic | Vertical derivative of the gravity dyke | 2.6e-08 % | 1.0e-04 % |
 | Poisson's relation | Vertical cylinder, gravity ↔ magnetic | Vertical derivative of the gravity cylinder | 3.6e-08 % | 1.0e-04 % |
 | Poisson's relation | Vertical contact, gravity ↔ magnetic | Vertical derivative of the gravity step | 3.9e-06 % | 1.0e-04 % |
+| Analytical limit | GPR, attenuation in a low-loss host | Low-loss limit 1636 σ/√εr dB/m (σ in S/m) | 1.1e-04 % | 0.01 % |
+| Analytical limit | GPR, velocity in a low-loss host | c/√εr | 2.5e-06 % | 1.0e-04 % |
+| 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 % |
 | 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 % |
@@ -164,7 +172,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.3.0) [Computer software].
+> Nergiz, M. (2026). *Detectability: Pre-survey detectability, modelled and reproducible* (Version 0.4.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.3.0 → detectability-0.4.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/gpr.py
 src/detectability/gravity.py
 src/detectability/igrf.py
 src/detectability/magnetics.py
@@ -18,6 +19,7 @@ src/detectability.egg-info/top_level.txt
 src/detectability/data/harmonica_reference.json
 src/detectability/data/igrf14coeffs.txt
 tests/test_detect.py
+tests/test_gpr.py
 tests/test_gravity.py
 tests/test_igrf.py
 tests/test_magnetics.py

detectability-0.4.0/tests/test_gpr.py

@@ -0,0 +1,102 @@
+import numpy as np
+import pytest
+
+from detectability import evaluate, gpr
+
+SITE = {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}
+
+
+def test_attenuation_within_published_ranges():
+    # Davis & Annan (1989) table (USACE 1995 Table 4-3): attenuation ranges in dB/m
+    ranges = {"dry sand": (0.005, 0.02), "wet sand": (0.03, 0.3), "limestone": (0.4, 1.0), "shale": (1, 100),
+              "silt": (1, 100), "clay": (1, 300), "granite": (0.01, 1), "rock salt": (0.01, 1), "fresh water": (0.05, 0.15)}
+    for name, (lo, hi) in ranges.items():
+        assert lo <= gpr.medium(name).attenuation_db(1e8) <= hi, name
+
+
+def test_sea_water_is_opaque():
+    assert gpr.medium("sea water").attenuation_db(1e8) > 100
+
+
+def test_reflection_limits():
+    lime = gpr.medium("limestone")
+    assert abs(gpr.reflection(lime, lime, 1e8)) == pytest.approx(0, abs=1e-12)
+    assert gpr.reflection(lime, None, 1e8) == -1
+    # a faster (lower permittivity) target gives a positive coefficient, a slower one negative
+    assert gpr.reflection(lime, gpr.medium("air"), 1e8).real > 0
+    assert gpr.reflection(lime, gpr.medium("fresh water"), 1e8).real < 0
+
+
+def test_size_factor_limits():
+    r = np.array([1.0, 5.0, 20.0])
+    lam = 0.5
+    assert np.allclose(gpr.size_factor("sphere", r, lam, a=1e9), 1.0)
+    assert np.allclose(gpr.size_factor("cylinder", r, lam, a=1e9), 1.0)
+    assert np.allclose(gpr.size_factor("disc", r, lam, a=1e3), 1.0)
+    small = gpr.size_factor("sphere", r, lam, a=0.01)
+    assert np.all(small < 1e-3)
+    # Rayleigh regime joins geometric optics continuously at k a = 1
+    a1 = lam / (2 * np.pi)
+    assert gpr.size_factor("sphere", r, lam, a=a1 * (1 - 1e-9)) == pytest.approx(gpr.size_factor("sphere", r, lam, a=a1))
+
+
+def test_frequency_for_depth_follows_the_rule():
+    assert gpr.frequency_for_depth(1.0) == 500
+    assert gpr.frequency_for_depth(10.0) == 50
+    assert gpr.frequency_for_depth(0.2) == 1000
+
+
+def test_echo_falls_with_depth_and_attenuation():
+    lime, clay = gpr.medium("limestone"), gpr.medium("clay")
+    R = gpr.reflection(lime, gpr.medium("air"), 2e8)
+    one = np.ones(2)
+    e = gpr.echo(np.array([2.0, 8.0]), lime, R, one, 2e8)
+    assert e[0] > e[1]
+    assert gpr.echo(np.array([2.0]), clay, R, np.ones(1), 2e8)[0] < e[0]
+
+
+def test_evaluate_gpr_void_in_limestone():
+    rep = evaluate({"shape": "sphere", "depth_top": 3, "size": 1, "material": "air", "host": "limestone"}, SITE,
+                   methods=["gpr"])
+    r = rep.result("gpr")
+    assert r.available and r.details["frequency_mhz"] == 200
+    assert r.assessment.verdict == "clearly detectable"
+    assert r.assessment.station_spacing <= r.details["vertical_resolution_m"]
+    assert r.details["velocity_m_per_ns"] == pytest.approx(0.1224, abs=1e-3)
+    assert "gpr (200 MHz)" in rep.summary()
+
+
+def test_deep_target_in_clay_is_not_detectable():
+    rep = evaluate({"shape": "sphere", "depth_top": 8, "size": 2, "material": "air", "host": "clay"}, SITE,
+                   methods=["gpr"])
+    assert rep.result("gpr").assessment.verdict == "not detectable"
+
+
+def test_metal_pipe_and_given_properties():
+    rep = evaluate({"shape": "horizontal_cylinder", "depth_top": 1, "size": 0.1, "material": "metal",
+                    "host": "soil", "host_permittivity": 9, "host_conductivity": 5}, SITE, methods=["gpr", "gravity"])
+    r = rep.result("gpr")
+    assert r.available and r.contrast == pytest.approx(1.0)
+    assert not rep.result("gravity").available
+
+
+def test_unavailable_cases():
+    contact = evaluate({"shape": "contact", "depth_top": 1, "depth_bottom": 5, "host": "limestone"}, SITE, methods=["gpr"])
+    assert not contact.result("gpr").available
+    unknown = evaluate({"shape": "sphere", "depth_top": 2, "size": 1, "host": "gabbro"}, SITE, methods=["gpr"])
+    assert "permittivity" in unknown.result("gpr").reason
+
+
+def test_lower_system_performance_lowers_snr():
+    t = {"shape": "prism", "depth_top": 4, "depth_bottom": 6, "size": 3, "material": "air", "host": "limestone"}
+    hi = evaluate(t, {**SITE, "gpr_system_performance": 120}, methods=["gpr"]).result("gpr").assessment.snr
+    lo = evaluate(t, {**SITE, "gpr_system_performance": 80}, methods=["gpr"]).result("gpr").assessment.snr
+    assert hi / lo == pytest.approx(100.0)  # 40 dB
+
+
+def test_script_reproduces_gpr():
+    rep = evaluate({"shape": "dyke", "depth_top": 2, "depth_bottom": 6, "size": 1, "material": "wet sand",
+                    "host": "granite"}, {**SITE, "gpr_frequency": 250}, methods=["gpr"])
+    ns = {}
+    exec(rep.script().replace("print(report.summary())", "").split("# Optional plot")[0], ns)
+    assert ns["report"].result("gpr").assessment.snr == pytest.approx(rep.result("gpr").assessment.snr)