detectability 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.2.1
+Version: 0.3.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
@@ -68,7 +69,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.2.1: sphere in limestone
+Detectability 0.3.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,24 @@ 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. The defaults are `gravity` and `magnetic`:
+
+```python
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
+```
+
 ## 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) |
 | `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 +126,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 % |
@@ -147,16 +157,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.3.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.3.0}/README.md

@@ -35,7 +35,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.2.1: sphere in limestone
+Detectability 0.3.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,24 @@ 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. The defaults are `gravity` and `magnetic`:
+
+```python
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
+```
+
 ## 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) |
 | `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 +92,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 % |
@@ -114,16 +123,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.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "detectability"
-version = "0.2.1"
+version = "0.3.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.3.0/src/detectability/__init__.py

@@ -0,0 +1,7 @@
+"""Detectability: pre-survey detectability, modelled and reproducible."""
+
+__version__ = "0.3.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.3.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"}
 
 
 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.2.1 → detectability-0.3.0}/src/detectability/survey.py

@@ -20,7 +20,8 @@ import numpy as np
 from . import __version__, detect, gravity, igrf, magnetics, rocks
 from .constants import SI_TO_UGAL
 
-METHODS = ("gravity", "magnetic")
+METHODS = ("gravity", "magnetic", "gradient")   # gradient: magnetic vertical gradient (two-sensor gradiometer)
+DEFAULT_METHODS = ("gravity", "magnetic")
 
 SHAPES: dict[str, str] = {
     "sphere": "Sphere (cavity, boulder, buried object). size = diameter.",
@@ -72,6 +73,11 @@ 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
@@ -261,7 +267,13 @@ 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 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()
@@ -295,18 +307,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 +345,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.3.0}/src/detectability/validation.py

@@ -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))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.2.1
+Version: 0.3.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
@@ -68,7 +69,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.2.1: sphere in limestone
+Detectability 0.3.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,24 @@ 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. The defaults are `gravity` and `magnetic`:
+
+```python
+evaluate(target, survey, methods=["gravity", "magnetic", "gradient"])
+```
+
 ## 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) |
 | `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 +126,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 % |
@@ -147,16 +157,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.3.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.3.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.2.1 → detectability-0.3.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__"]