detectability 0.2.1__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.2.1
+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
@@ -9,6 +9,7 @@ Project-URL: Documentation, https://detectability.mukreminnergiz.com/method
 Project-URL: Validation, https://detectability.mukreminnergiz.com/validation
 Project-URL: Repository, https://github.com/mukremin-nergiz/detectability
 Project-URL: Issues, https://github.com/mukremin-nergiz/detectability/issues
+Project-URL: Changelog, https://github.com/mukremin-nergiz/detectability/blob/main/CHANGELOG.md
 Project-URL: Citation, https://doi.org/10.5281/zenodo.23931815
 Keywords: geophysics,gravity,magnetics,survey design,near-surface,forward modelling,IGRF
 Classifier: Development Status :: 3 - Alpha
@@ -33,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
@@ -68,7 +69,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.2.1: 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
@@ -82,16 +83,27 @@ Target shapes: `sphere`, `horizontal_cylinder`, `vertical_cylinder`, `prism`, `d
 geomagnetic field comes from IGRF-14 for the survey location and date. Typical densities and susceptibilities are built
 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; 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", "gpr"])
+```
+
 ## Modules
 
 | Module | Contents |
 |---|---|
 | `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 |
+| `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 and field noise, signal-to-noise ratio, verdict, station spacing, profile length |
+| `detect` | instrument presets with their sources (gravimeters, magnetometers, gradiometers), field noise, signal-to-noise ratio, verdict, station spacing, profile length |
 
 ## Validation
 
@@ -117,6 +129,7 @@ python tools/harmonica_reference.py --check
 | Analytical limit | Vertical cylinder, gravity, on its axis | Exact on-axis cylinder formula | 1.7e-13 % | 1.0e-10 % |
 | Independent formula | Horizontal cylinder, gravity | 2D polygon, 720 sides (Talwani; Won & Bevis) | 6.3e-12 % | 0.01 % |
 | Independent formula | Vertical dyke, gravity | 2D polygon (Won & Bevis) | 1.9e-13 % | 1.0e-06 % |
+| Independent formula | Sphere, magnetic gradient (gradiometer reading) | Closed-form vertical-dipole field at both sensors | 7.8e-14 % | 1.0e-10 % |
 | Numerical integration | Prism, gravity | 16³ Gauss–Legendre point masses | 2.9e-06 % | 0.001 % |
 | Numerical integration | Horizontal cylinder, magnetic | 3D dipoles integrated along strike | 2.2e-07 % | 0.01 % |
 | Numerical integration | Prism, magnetic | 16³ Gauss–Legendre point dipoles | 1.3e-12 % | 0.001 % |
@@ -127,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 % |
@@ -147,16 +165,18 @@ pytest
 Flat topography, a homogeneous host and no regional trend; 2D targets are infinitely long along strike; the profile
 crosses the centre of the target; self-demagnetisation is neglected. Results are expectations under these assumptions,
 not guarantees. Instrument presets come from manufacturers' data sheets (`detect.INSTRUMENTS` lists each figure and its
-source); field noise, which usually dominates, is a stated assumption that you can change.
+source); field noise, which usually dominates, is a stated assumption that you can change. For gradiometers the default
+field noise (0.5 nT) is an assumption, not a published figure: soil, heading and walking noise depend on the site.
 
 ## Citation
 
 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.2.1) [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.
+The DOI above always resolves to the latest version; each release also has its own DOI on Zenodo. Changes between
+releases: [CHANGELOG.md](https://github.com/mukremin-nergiz/detectability/blob/main/CHANGELOG.md).
 
 ## Author
 

{detectability-0.2.1 → 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.2.1: 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
@@ -49,16 +49,27 @@ Target shapes: `sphere`, `horizontal_cylinder`, `vertical_cylinder`, `prism`, `d
 geomagnetic field comes from IGRF-14 for the survey location and date. Typical densities and susceptibilities are built
 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; 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", "gpr"])
+```
+
 ## Modules
 
 | Module | Contents |
 |---|---|
 | `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 |
+| `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 and field noise, signal-to-noise ratio, verdict, station spacing, profile length |
+| `detect` | instrument presets with their sources (gravimeters, magnetometers, gradiometers), field noise, signal-to-noise ratio, verdict, station spacing, profile length |
 
 ## Validation
 
@@ -84,6 +95,7 @@ python tools/harmonica_reference.py --check
 | Analytical limit | Vertical cylinder, gravity, on its axis | Exact on-axis cylinder formula | 1.7e-13 % | 1.0e-10 % |
 | Independent formula | Horizontal cylinder, gravity | 2D polygon, 720 sides (Talwani; Won & Bevis) | 6.3e-12 % | 0.01 % |
 | Independent formula | Vertical dyke, gravity | 2D polygon (Won & Bevis) | 1.9e-13 % | 1.0e-06 % |
+| Independent formula | Sphere, magnetic gradient (gradiometer reading) | Closed-form vertical-dipole field at both sensors | 7.8e-14 % | 1.0e-10 % |
 | Numerical integration | Prism, gravity | 16³ Gauss–Legendre point masses | 2.9e-06 % | 0.001 % |
 | Numerical integration | Horizontal cylinder, magnetic | 3D dipoles integrated along strike | 2.2e-07 % | 0.01 % |
 | Numerical integration | Prism, magnetic | 16³ Gauss–Legendre point dipoles | 1.3e-12 % | 0.001 % |
@@ -94,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 % |
@@ -114,16 +131,18 @@ pytest
 Flat topography, a homogeneous host and no regional trend; 2D targets are infinitely long along strike; the profile
 crosses the centre of the target; self-demagnetisation is neglected. Results are expectations under these assumptions,
 not guarantees. Instrument presets come from manufacturers' data sheets (`detect.INSTRUMENTS` lists each figure and its
-source); field noise, which usually dominates, is a stated assumption that you can change.
+source); field noise, which usually dominates, is a stated assumption that you can change. For gradiometers the default
+field noise (0.5 nT) is an assumption, not a published figure: soil, heading and walking noise depend on the site.
 
 ## Citation
 
 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.2.1) [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.
+The DOI above always resolves to the latest version; each release also has its own DOI on Zenodo. Changes between
+releases: [CHANGELOG.md](https://github.com/mukremin-nergiz/detectability/blob/main/CHANGELOG.md).
 
 ## Author
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "detectability"
-version = "0.2.1"
+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"]
@@ -31,6 +31,7 @@ Documentation = "https://detectability.mukreminnergiz.com/method"
 Validation = "https://detectability.mukreminnergiz.com/validation"
 Repository = "https://github.com/mukremin-nergiz/detectability"
 Issues = "https://github.com/mukremin-nergiz/detectability/issues"
+Changelog = "https://github.com/mukremin-nergiz/detectability/blob/main/CHANGELOG.md"
 Citation = "https://doi.org/10.5281/zenodo.23931815"
 
 [project.optional-dependencies]

detectability-0.4.0/src/detectability/__init__.py

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

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

@@ -19,11 +19,12 @@ STATIONS_ACROSS = 5
 class Instrument:
     """An instrument preset: its noise, what the figure means and where it comes from (checked 4 Nov 2026)."""
 
-    method: str          # "gravity" or "magnetic"
-    noise: float         # one standard deviation of a reading, in µGal (gravity) or nT (magnetic)
+    method: str          # "gravity", "magnetic" or "gradient" (magnetic vertical gradient)
+    noise: float         # one standard deviation of a reading, in µGal (gravity) or nT (magnetic and gradient)
     basis: str           # what the manufacturer's figure is
     reference: str       # instrument the figure is taken from
     source: str          # data sheet or publication
+    baseline: float | None = None   # m, vertical distance between the two sensors (gradiometers)
 
 
 INSTRUMENTS: dict[str, Instrument] = {
@@ -45,18 +46,37 @@ INSTRUMENTS: dict[str, Instrument] = {
     "caesium vapour": Instrument(
         "magnetic", 0.008, "noise < 0.008 nT/√Hz RMS, i.e. at 1 Hz", "Geometrics G-858",
         "https://www.geomatrix.co.uk/land-products/magnetic/g-858/"),
+    # Vertical gradiometers: two sensors one above the other; the reading is the lower minus the upper sensor, in nT
+    # over the baseline (as Bartington and Foerster report it; nT/m only for a 1 m baseline).
+    "Bartington Grad601": Instrument(
+        "gradient", 0.1, "noise 100 pT peak-to-peak maximum, taken as one standard deviation to be conservative",
+        "Bartington Grad-01-1000L sensor (Grad601)", "https://www.bartingtondownloads.com/wp-content/uploads/DS0060.pdf",
+        baseline=1.0),
+    "Sensys FGM650": Instrument(
+        "gradient", 0.04, "noise < 40 pT rms/√Hz at 1 Hz", "Sensys FGM650 fluxgate gradiometer",
+        "https://sensysmagnetometer.com/de/produkte/fgm650-gradiometer/", baseline=0.65),
+    "Foerster FEREX 4.034": Instrument(
+        "gradient", 0.04, "noise < 40 pT/√Hz at 1 Hz (MG-10 probe)", "Foerster FEREX 4.034 with MG-10-550 probe",
+        "https://www.foerstergroup.com/FOERSTER/downloads/product/ferex/FOERSTER_FLY_FEREX4.034_DE.pdf", baseline=0.55),
+    "GEM GSM-19G": Instrument(
+        "gradient", 0.031, "0.022 nT at 1 Hz per sensor; two sensors in difference give 0.022 × √2",
+        "GEM Systems GSM-19G Overhauser gradiometer (one staff section, 0.56 m, per the manual)",
+        "https://www.gemsys.ca/wp-content/themes/gemsystems/pdf/GEM_Overhauser_GSM_19_fin.pdf", baseline=0.56),
 }
-# Fluxgate gradiometers (e.g. Bartington Grad601) measure a vertical gradient, not the total-field anomaly modelled
-# here, so they are not offered until a gradiometer response is implemented.
 
 GRAVIMETERS_UGAL: dict[str, float] = {k: v.noise for k, v in INSTRUMENTS.items() if v.method == "gravity"}
 MAGNETOMETERS_NT: dict[str, float] = {k: v.noise for k, v in INSTRUMENTS.items() if v.method == "magnetic"}
+GRADIOMETERS_NT: dict[str, float] = {k: v.noise for k, v in INSTRUMENTS.items() if v.method == "gradient"}
 
 # Field noise is what remains after corrections and usually dominates the instrument noise.
 DEFAULT_FIELD_NOISE_UGAL = 10.0  # microgravity: tares, drift residuals, terrain, cultural noise
 DEFAULT_FIELD_NOISE_NT = 2.0     # quiet rural site after diurnal correction; urban and industrial sites are far noisier
+# Gradient surveys cancel diurnal variation and the regional field, so their field noise is mainly soil, heading and
+# walking noise. 0.5 nT is an assumption, not a published figure (the Grad601 manual asks for a set-up spot that varies
+# 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"}
+UNITS = {"gravity": "µGal", "magnetic": "nT", "gradient": "nT", "gpr": "× detection limit"}
 
 
 def effective_noise(instrument: float, field_noise: float) -> float:
@@ -143,7 +163,7 @@ def assess(x, anomaly, noise: float, depth: float, method: str = "gravity") -> A
         f"Station spacing allows at least {STATIONS_ACROSS} stations across the anomaly width ({width:.3g} m).",
         "Flat topography, homogeneous host and no regional trend; terrain and regional effects reduce the margin.",
     ]
-    if method == "magnetic":
+    if method in ("magnetic", "gradient"):
         assumptions.append("Peak is the largest absolute value of the (often two-lobed) anomaly; no remanence unless given.")
     return Assessment(method, peak, float(x[peak_i]), width, shape, noise, snr, verdict, spacing, length, assumptions,
                       unit)

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.2.1 → detectability-0.4.0}/src/detectability/survey.py

@@ -17,10 +17,11 @@ 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")
+METHODS = ("gravity", "magnetic", "gradient", "gpr")   # gradient: magnetic vertical gradient; gpr: ground-penetrating radar
+DEFAULT_METHODS = ("gravity", "magnetic")
 
 SHAPES: dict[str, str] = {
     "sphere": "Sphere (cavity, boulder, buried object). size = diameter.",
@@ -49,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:
@@ -72,10 +77,17 @@ class Survey:
     magnetic_field_noise: float = detect.DEFAULT_FIELD_NOISE_NT       # nT
     magnetic_instrument_noise: float | None = None                    # nT, overrides the magnetometer preset
     sensor_height: float = 0.5            # m, magnetometer sensor above ground
+    gradiometer: str = "Bartington Grad601"
+    gradient_field_noise: float = detect.DEFAULT_FIELD_NOISE_GRADIENT_NT   # nT, of the gradiometer reading
+    gradient_instrument_noise: float | None = None                         # nT, overrides the gradiometer preset
+    gradiometer_height: float = 0.2       # m, lower sensor above ground (Bartington: about 20 cm in normal use)
+    gradiometer_baseline: float | None = None   # m between the sensors; default: the gradiometer preset's
     profile_azimuth: float = 0.0          # degrees east of north; 2D targets strike at right angles to it
     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
@@ -95,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
@@ -123,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")
@@ -261,7 +280,106 @@ def _main_field(s: Survey):
                                            "inclination": round(f.inclination, 3), "declination": round(f.declination, 3)}
 
 
-def evaluate(target, survey=None, methods=METHODS) -> Report:
+def _gradient(t: Target, x, chi, amb, s: Survey, baseline: float):
+    """Gradiometer reading: total-field anomaly at the lower sensor minus that at the upper sensor, in nT."""
+    low, high = replace(s, sensor_height=s.gradiometer_height), replace(s, sensor_height=s.gradiometer_height + baseline)
+    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)
     t.validate()
@@ -275,6 +393,9 @@ def evaluate(target, survey=None, methods=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))
@@ -295,18 +416,36 @@ def evaluate(target, survey=None, methods=METHODS) -> Report:
                 results.append(MethodResult(method, False, "needs the survey location (latitude, longitude) for the "
                                             "main field, or field_total/inclination/declination"))
                 continue
-            inst = s.magnetic_instrument_noise if s.magnetic_instrument_noise is not None else \
-                detect.MAGNETOMETERS_NT.get(s.magnetometer)
-            if inst is None:
-                results.append(MethodResult(method, False, f"unknown magnetometer {s.magnetometer!r}"))
-                continue
-            noise = detect.effective_noise(inst, s.magnetic_field_noise)
-            anomaly = _magnetic(t, x, contrast, amb, s)
-            res = MethodResult(method, True, contrast=contrast, contrast_units=units, instrument=s.magnetometer,
-                               instrument_noise=inst, field_noise=s.magnetic_field_noise, main_field=info)
+            if method == "magnetic":
+                inst = s.magnetic_instrument_noise if s.magnetic_instrument_noise is not None else \
+                    detect.MAGNETOMETERS_NT.get(s.magnetometer)
+                if inst is None:
+                    results.append(MethodResult(method, False, f"unknown magnetometer {s.magnetometer!r}"))
+                    continue
+                noise = detect.effective_noise(inst, s.magnetic_field_noise)
+                anomaly = _magnetic(t, x, contrast, amb, s)
+                res = MethodResult(method, True, contrast=contrast, contrast_units=units, instrument=s.magnetometer,
+                                   instrument_noise=inst, field_noise=s.magnetic_field_noise, main_field=info)
+            else:
+                preset = detect.INSTRUMENTS.get(s.gradiometer)
+                inst = s.gradient_instrument_noise if s.gradient_instrument_noise is not None else \
+                    (preset.noise if preset and preset.method == "gradient" else None)
+                baseline = s.gradiometer_baseline if s.gradiometer_baseline is not None else \
+                    (preset.baseline if preset and preset.method == "gradient" else None)
+                if inst is None or baseline is None:
+                    results.append(MethodResult(method, False, f"unknown gradiometer {s.gradiometer!r} (or give "
+                                                "gradient_instrument_noise and gradiometer_baseline)"))
+                    continue
+                if baseline <= 0 or s.gradiometer_height < 0:
+                    raise ValueError("gradiometer_baseline must be positive and gradiometer_height zero or positive")
+                noise = detect.effective_noise(inst, s.gradient_field_noise)
+                anomaly = _gradient(t, x, contrast, amb, s, baseline)
+                res = MethodResult(method, True, contrast=contrast, contrast_units=units, instrument=s.gradiometer,
+                                   instrument_noise=inst, field_noise=s.gradient_field_noise, main_field=info)
         a = detect.assess(x, anomaly, noise, depth=t.depth_top, method=method)
         preset = detect.INSTRUMENTS.get(res.instrument)
-        overridden = (s.gravity_instrument_noise if method == "gravity" else s.magnetic_instrument_noise) is not None
+        overridden = {"gravity": s.gravity_instrument_noise, "magnetic": s.magnetic_instrument_noise,
+                      "gradient": s.gradient_instrument_noise}[method] is not None
         if preset and not overridden:
             a.assumptions.append(f"{res.instrument}: {preset.noise:g} {a.units} per reading ({preset.basis}; "
                                  f"{preset.reference} data sheet).")
@@ -315,6 +454,11 @@ def evaluate(target, survey=None, methods=METHODS) -> Report:
         if method == "magnetic":
             a.assumptions.append(f"Sensor {s.sensor_height:g} m above ground; profile azimuth {s.profile_azimuth:g}°; "
                                  "induced magnetisation only, no demagnetisation.")
+        if method == "gradient":
+            top = s.gradiometer_height + baseline
+            a.assumptions.append(f"Reading: lower sensor ({s.gradiometer_height:g} m above ground) minus upper sensor "
+                                 f"({top:g} m), in nT over the {baseline:g} m baseline; diurnal variation and the regional "
+                                 f"field cancel. Profile azimuth {s.profile_azimuth:g}°; induced magnetisation only.")
         res.x, res.anomaly, res.assessment = x.round(4).tolist(), anomaly.tolist(), a
         results.append(res)
 

{detectability-0.2.1 → 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
 
@@ -240,6 +240,24 @@ def cases() -> list[Case]:
         gravity.dyke(x, 3, 15, 4, 500.0, centre=7) * SI_TO_UGAL,
         gravity.polygon(x, [(5, 3), (9, 3), (9, 15), (5, 15)], 500.0) * SI_TO_UGAL))
 
+    # gradiometer reading of a sphere at the pole: closed-form dipole field at the two sensor heights
+    x = np.linspace(-20, 20, 81)
+    depth, radius, low, base = 3.0, 0.5, 0.2, 1.0
+    m = CHI * POLE.total * 1e-9 / MU0 * 4 / 3 * np.pi * radius**3
+
+    def _pole_dipole(h):
+        z = depth + h                          # depth of the centre below the sensor
+        return MU0 / (4 * np.pi) * m * (2 * z**2 - x**2) / (x**2 + z**2) ** 2.5 * 1e9
+
+    from .survey import _gradient, Survey, Target
+    sphere_target = Target("sphere", depth - radius, 2 * radius)
+    reading = _gradient(sphere_target, x, CHI, POLE, Survey(gradiometer_height=low), base)
+    out.append(_profile_case(
+        "gradient-sphere-pole", "Independent formula", "Sphere, magnetic gradient (gradiometer reading)",
+        "Total-field model at the lower minus the upper sensor", "Closed-form vertical-dipole field at both sensors",
+        "Radius 0.5 m, centre at 3 m, sensors 0.2 and 1.2 m above ground, at the pole", "nT", 1e-10, x, reading,
+        _pole_dipole(low) - _pole_dipole(low + base)))
+
     # --- numerical integration -------------------------------------------------------------------------------
     x = np.linspace(-40, 40, 81)
     box = ((-3.0, 3.0), (-4.0, 4.0), (2.0, 6.0))
@@ -312,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.2.1 → detectability-0.4.0/src/detectability.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.2.1
+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
@@ -9,6 +9,7 @@ Project-URL: Documentation, https://detectability.mukreminnergiz.com/method
 Project-URL: Validation, https://detectability.mukreminnergiz.com/validation
 Project-URL: Repository, https://github.com/mukremin-nergiz/detectability
 Project-URL: Issues, https://github.com/mukremin-nergiz/detectability/issues
+Project-URL: Changelog, https://github.com/mukremin-nergiz/detectability/blob/main/CHANGELOG.md
 Project-URL: Citation, https://doi.org/10.5281/zenodo.23931815
 Keywords: geophysics,gravity,magnetics,survey design,near-surface,forward modelling,IGRF
 Classifier: Development Status :: 3 - Alpha
@@ -33,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
@@ -68,7 +69,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.2.1: 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
@@ -82,16 +83,27 @@ Target shapes: `sphere`, `horizontal_cylinder`, `vertical_cylinder`, `prism`, `d
 geomagnetic field comes from IGRF-14 for the survey location and date. Typical densities and susceptibilities are built
 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; 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", "gpr"])
+```
+
 ## Modules
 
 | Module | Contents |
 |---|---|
 | `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 |
+| `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 and field noise, signal-to-noise ratio, verdict, station spacing, profile length |
+| `detect` | instrument presets with their sources (gravimeters, magnetometers, gradiometers), field noise, signal-to-noise ratio, verdict, station spacing, profile length |
 
 ## Validation
 
@@ -117,6 +129,7 @@ python tools/harmonica_reference.py --check
 | Analytical limit | Vertical cylinder, gravity, on its axis | Exact on-axis cylinder formula | 1.7e-13 % | 1.0e-10 % |
 | Independent formula | Horizontal cylinder, gravity | 2D polygon, 720 sides (Talwani; Won & Bevis) | 6.3e-12 % | 0.01 % |
 | Independent formula | Vertical dyke, gravity | 2D polygon (Won & Bevis) | 1.9e-13 % | 1.0e-06 % |
+| Independent formula | Sphere, magnetic gradient (gradiometer reading) | Closed-form vertical-dipole field at both sensors | 7.8e-14 % | 1.0e-10 % |
 | Numerical integration | Prism, gravity | 16³ Gauss–Legendre point masses | 2.9e-06 % | 0.001 % |
 | Numerical integration | Horizontal cylinder, magnetic | 3D dipoles integrated along strike | 2.2e-07 % | 0.01 % |
 | Numerical integration | Prism, magnetic | 16³ Gauss–Legendre point dipoles | 1.3e-12 % | 0.001 % |
@@ -127,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 % |
@@ -147,16 +165,18 @@ pytest
 Flat topography, a homogeneous host and no regional trend; 2D targets are infinitely long along strike; the profile
 crosses the centre of the target; self-demagnetisation is neglected. Results are expectations under these assumptions,
 not guarantees. Instrument presets come from manufacturers' data sheets (`detect.INSTRUMENTS` lists each figure and its
-source); field noise, which usually dominates, is a stated assumption that you can change.
+source); field noise, which usually dominates, is a stated assumption that you can change. For gradiometers the default
+field noise (0.5 nT) is an assumption, not a published figure: soil, heading and walking noise depend on the site.
 
 ## Citation
 
 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.2.1) [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.
+The DOI above always resolves to the latest version; each release also has its own DOI on Zenodo. Changes between
+releases: [CHANGELOG.md](https://github.com/mukremin-nergiz/detectability/blob/main/CHANGELOG.md).
 
 ## Author
 

{detectability-0.2.1 → 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.2.1 → detectability-0.4.0}/tests/test_detect.py

@@ -66,8 +66,17 @@ def test_void_in_limestone_magnetic_example():
 def test_instrument_presets_have_sources():
     assert detect.INSTRUMENTS
     for name, inst in detect.INSTRUMENTS.items():
-        assert inst.method in ("gravity", "magnetic"), name
+        assert inst.method in ("gravity", "magnetic", "gradient"), name
         assert inst.noise > 0 and inst.source.startswith("https://") and inst.reference, name
     assert detect.GRAVIMETERS_UGAL["Scintrex CG-6"] == 5.0
     assert detect.MAGNETOMETERS_NT["Overhauser"] == 0.022
-    assert "fluxgate gradiometer" not in detect.MAGNETOMETERS_NT  # measures a gradient, not the total field
+    assert "Bartington Grad601" not in detect.MAGNETOMETERS_NT  # a gradiometer reading, not the total field
+
+
+def test_gradiometer_presets_have_a_baseline_and_a_source():
+    grads = {k: v for k, v in detect.INSTRUMENTS.items() if v.method == "gradient"}
+    assert len(grads) >= 3 and set(grads) == set(detect.GRADIOMETERS_NT)
+    for name, inst in grads.items():
+        assert inst.baseline and 0.3 <= inst.baseline <= 1.5, name
+        assert inst.source.startswith("https://") and inst.noise > 0, name
+    assert all(v.baseline is None for v in detect.INSTRUMENTS.values() if v.method != "gradient")

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)

{detectability-0.2.1 → detectability-0.4.0}/tests/test_survey.py

@@ -75,3 +75,43 @@ def test_dataclass_inputs_are_not_modified():
     s = Survey(latitude=39.75, longitude=37.02)
     evaluate(Target(**VOID), s)
     assert s.date is None
+
+
+SITE = {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}
+SHALLOW_DYKE = {"shape": "dyke", "depth_top": 0.4, "depth_bottom": 1.2, "size": 0.8, "material": "basalt",
+                "host": "sandstone"}
+
+
+def test_default_methods_unchanged_and_gradient_on_request():
+    from detectability import DEFAULT_METHODS, METHODS
+    assert DEFAULT_METHODS == ("gravity", "magnetic") and "gradient" in METHODS
+    assert [r.method for r in evaluate(SHALLOW_DYKE, SITE).results] == ["gravity", "magnetic"]
+    r = evaluate(SHALLOW_DYKE, SITE, ["gradient"]).results[0]
+    assert r.available and r.instrument == "Bartington Grad601" and r.assessment.units == "nT"
+
+
+def test_gradient_is_the_difference_of_two_sensor_heights():
+    import numpy as np
+    low = evaluate(SHALLOW_DYKE, {**SITE, "sensor_height": 0.3}, ["magnetic"]).results[0]
+    high = evaluate(SHALLOW_DYKE, {**SITE, "sensor_height": 0.95}, ["magnetic"]).results[0]
+    g = evaluate(SHALLOW_DYKE, {**SITE, "gradiometer": "Sensys FGM650", "gradiometer_height": 0.3}, ["gradient"])
+    assert np.allclose(g.results[0].anomaly, np.subtract(low.anomaly, high.anomaly), rtol=0, atol=1e-12)
+
+
+def test_gradient_favours_shallow_targets():
+    deep = {"shape": "sphere", "depth_top": 15, "size": 20, "material": "air", "host": "limestone"}
+    shallow = evaluate(SHALLOW_DYKE, SITE, ["magnetic", "gradient"])
+    assert shallow.recommended == "gradient"
+    far = evaluate(deep, SITE, ["magnetic", "gradient"]).results
+    assert far[1].assessment.snr < far[0].assessment.snr
+
+
+def test_custom_gradiometer_and_errors():
+    import pytest
+    r = evaluate(SHALLOW_DYKE, {**SITE, "gradiometer": "home-made", "gradient_instrument_noise": 0.05,
+                                "gradiometer_baseline": 0.5}, ["gradient"]).results[0]
+    assert r.available and r.instrument_noise == 0.05
+    assert not evaluate(SHALLOW_DYKE, {**SITE, "gradiometer": "home-made"}, ["gradient"]).results[0].available
+    assert not evaluate(SHALLOW_DYKE, {}, ["gradient"]).results[0].available          # needs the location
+    with pytest.raises(ValueError):
+        evaluate(SHALLOW_DYKE, {**SITE, "gradiometer_baseline": 0}, ["gradient"])

detectability-0.2.1/src/detectability/__init__.py

@@ -1,7 +0,0 @@
-"""Detectability: pre-survey detectability, modelled and reproducible."""
-
-__version__ = "0.2.1"
-
-from .survey import METHODS, SHAPES, Report, Survey, Target, evaluate  # noqa: E402
-
-__all__ = ["evaluate", "Target", "Survey", "Report", "SHAPES", "METHODS", "__version__"]