detectability 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.5.0
+Version: 0.6.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
@@ -71,7 +71,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.5.0: sphere in limestone
+Detectability 0.6.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
@@ -81,6 +81,29 @@ Recommended method: gravity
 `report.script()` returns a standalone script that recomputes the report; `report.to_dict()` gives the full result,
 including the modelled profiles and the assumptions.
 
+### How deep before a method loses it?
+
+`depth_limit()` asks the inverse question — the one a survey plan turns on. Leave `depth_top` out: it is what the
+search solves for.
+
+```python
+from detectability import depth_limit
+
+for method in ("gravity", "magnetic", "gpr"):
+    print(depth_limit({"shape": "sphere", "size": 20, "material": "air", "host": "limestone"},
+                      {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}, method=method))
+```
+
+```text
+gravity: detectable (S/N >= 5) down to 25.7 m
+magnetic: never reaches S/N 5; S/N 2.88 even at 0.5 m
+gpr: detectable (S/N >= 5) down to 25.2 m
+```
+
+Pass `threshold=detect.MARGINAL` for the lower threshold, and `search=(shallow, deep)` to bound the sweep.
+Sweep the target size and you have a detection-limit chart; the website draws one at
+[/limits](https://detectability.mukreminnergiz.com/limits).
+
 Target shapes: `sphere`, `horizontal_cylinder`, `vertical_cylinder`, `prism`, `dyke` (any dip) and `contact`. The main
 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.

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

@@ -35,7 +35,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.5.0: sphere in limestone
+Detectability 0.6.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
@@ -45,6 +45,29 @@ Recommended method: gravity
 `report.script()` returns a standalone script that recomputes the report; `report.to_dict()` gives the full result,
 including the modelled profiles and the assumptions.
 
+### How deep before a method loses it?
+
+`depth_limit()` asks the inverse question — the one a survey plan turns on. Leave `depth_top` out: it is what the
+search solves for.
+
+```python
+from detectability import depth_limit
+
+for method in ("gravity", "magnetic", "gpr"):
+    print(depth_limit({"shape": "sphere", "size": 20, "material": "air", "host": "limestone"},
+                      {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}, method=method))
+```
+
+```text
+gravity: detectable (S/N >= 5) down to 25.7 m
+magnetic: never reaches S/N 5; S/N 2.88 even at 0.5 m
+gpr: detectable (S/N >= 5) down to 25.2 m
+```
+
+Pass `threshold=detect.MARGINAL` for the lower threshold, and `search=(shallow, deep)` to bound the sweep.
+Sweep the target size and you have a detection-limit chart; the website draws one at
+[/limits](https://detectability.mukreminnergiz.com/limits).
+
 Target shapes: `sphere`, `horizontal_cylinder`, `vertical_cylinder`, `prism`, `dyke` (any dip) and `contact`. The main
 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.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "detectability"
-version = "0.5.0"
+version = "0.6.0"
 description = "Pre-survey detectability, modelled and reproducible: forward-modelled gravity and magnetic responses, station spacing and a detectability verdict for near-surface targets."
 readme = "README.md"
 keywords = ["geophysics", "gravity", "magnetics", "survey design", "near-surface", "forward modelling", "IGRF"]

detectability-0.6.0/src/detectability/__init__.py

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

detectability-0.6.0/src/detectability/limits.py

@@ -0,0 +1,121 @@
+"""How deep a method still sees a target: the depth limit, solved for instead of assumed.
+
+``evaluate`` answers "can this method see the target at this depth?". The inverse question is the one that shapes a
+survey plan: *how deep can the target be before the method loses it?*
+
+    >>> from detectability import depth_limit
+    >>> limit = depth_limit({"shape": "sphere", "size": 20, "material": "air", "host": "limestone"},
+    ...                     {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}, method="gravity")
+    >>> print(limit)
+
+``depth_top`` on the target is ignored, and may be left out entirely: it is what the search solves for. If the shape
+also needs ``depth_bottom``, the body keeps its thickness as it moves down.
+
+The search makes no assumption that signal-to-noise falls smoothly with depth, because it does not always: the GPR
+antenna frequency, when left to the default, is chosen from the target depth, so the response can step. A coarse
+geometric scan brackets the **shallowest** crossing of the threshold and a bisection refines it. The shallowest
+crossing is the honest answer — beyond it the method can no longer be relied on, whatever happens deeper.
+
+Each limit costs ``steps`` plus about twenty forward models. That is milliseconds for gravity, magnetics and GPR.
+For ERT, where a single forward model inverts a mesh and takes tens of seconds, a limit takes tens of minutes; pass a
+narrow ``search`` range and a small ``steps`` if you ask for one at all.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from . import detect
+from .survey import NEEDS_BOTTOM, Survey, Target, _as, evaluate
+
+__all__ = ["Limit", "depth_limit"]
+
+SEARCH = (0.5, 2000.0)      # m below ground: shallow enough for utilities, deep enough for an ore body
+STEPS = 24                  # coarse scan points, geometric over the search range
+REFINE = 20                 # bisections; takes a 24-point scan of 0.5-2000 m below 0.1 % in depth
+
+
+@dataclass
+class Limit:
+    """The greatest depth at which ``method`` still reaches ``threshold`` for a given target."""
+
+    method: str
+    threshold: float
+    depth: float | None             # m to the top of the target; None when the method never reaches the threshold
+    snr_shallowest: float | None    # signal-to-noise at the shallowest depth searched, for context
+    search: tuple[float, float]
+    beyond_search: bool = False     # still detected at the deepest depth searched: the limit is at least that
+    available: bool = True
+    reason: str = ""
+
+    def __str__(self) -> str:
+        if not self.available:
+            return f"{self.method}: not assessed ({self.reason})"
+        if self.depth is None:
+            return (f"{self.method}: never reaches S/N {self.threshold:g}; "
+                    f"S/N {self.snr_shallowest:.3g} even at {self.search[0]:g} m")
+        at_least = "at least " if self.beyond_search else ""
+        return f"{self.method}: detectable (S/N >= {self.threshold:g}) down to {at_least}{self.depth:.3g} m"
+
+
+def _at(target: Target, depth: float) -> Target:
+    """The same body, moved so its top sits at ``depth``; thickness kept where the shape needs a bottom."""
+    moved = replace(target, depth_top=depth)
+    if target.shape in NEEDS_BOTTOM:
+        thickness = (target.depth_bottom - target.depth_top) if target.depth_bottom else max(target.size or 1.0, 1.0)
+        moved.depth_bottom = depth + thickness
+    return moved
+
+
+def depth_limit(target, survey=None, method: str = "gravity", threshold: float = detect.CLEAR,
+                search: tuple[float, float] = SEARCH, steps: int = STEPS, refine: int = REFINE) -> Limit:
+    """Greatest depth at which ``method`` still reaches ``threshold`` for ``target`` under ``survey``.
+
+    ``threshold`` defaults to the clearly-detectable signal-to-noise (5); pass ``detect.MARGINAL`` for the lower one.
+    The result's ``depth`` is None when the method never reaches the threshold, even at the shallowest depth searched.
+    """
+    shallow, deep = float(search[0]), float(search[1])
+    if not 0 < shallow < deep:
+        raise ValueError(f"search must be (shallow, deep) with 0 < shallow < deep; got {search!r}")
+    if steps < 2:
+        raise ValueError("steps must be at least 2")
+
+    if isinstance(target, dict) and "depth_top" not in target:
+        target = {**target, "depth_top": shallow}   # it is what the search solves for; any value will do
+    t, s = _as(Target, target), _as(Survey, survey)
+    t.validate()
+
+    def snr(depth: float) -> tuple[float, bool, str]:
+        result = evaluate(_at(t, depth), s, methods=[method]).results[0]
+        if not result.available:
+            return 0.0, False, result.reason
+        return result.assessment.snr, True, ""
+
+    first, ok, why = snr(shallow)
+    if not ok:
+        return Limit(method, threshold, None, None, (shallow, deep), available=False, reason=why)
+    if first < threshold:
+        return Limit(method, threshold, None, first, (shallow, deep))
+
+    # Coarse scan for the shallowest crossing, then bisect inside that bracket.
+    ratio = (deep / shallow) ** (1 / (steps - 1))
+    lo, lo_depth = shallow, shallow
+    for i in range(1, steps):
+        probe = shallow * ratio ** i
+        value, ok, _ = snr(probe)
+        if not ok or value < threshold:
+            hi = probe
+            break
+        lo_depth = probe
+    else:
+        return Limit(method, threshold, deep, first, (shallow, deep), beyond_search=True)
+
+    lo = lo_depth
+    for _ in range(refine):
+        mid = (lo * hi) ** 0.5
+        value, ok, _ = snr(mid)
+        if ok and value >= threshold:
+            lo = mid
+        else:
+            hi = mid
+    return Limit(method, threshold, (lo * hi) ** 0.5, first, (shallow, deep))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectability
-Version: 0.5.0
+Version: 0.6.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
@@ -71,7 +71,7 @@ print(report.summary())
 ```
 
 ```text
-Detectability 0.5.0: sphere in limestone
+Detectability 0.6.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
@@ -81,6 +81,29 @@ Recommended method: gravity
 `report.script()` returns a standalone script that recomputes the report; `report.to_dict()` gives the full result,
 including the modelled profiles and the assumptions.
 
+### How deep before a method loses it?
+
+`depth_limit()` asks the inverse question — the one a survey plan turns on. Leave `depth_top` out: it is what the
+search solves for.
+
+```python
+from detectability import depth_limit
+
+for method in ("gravity", "magnetic", "gpr"):
+    print(depth_limit({"shape": "sphere", "size": 20, "material": "air", "host": "limestone"},
+                      {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}, method=method))
+```
+
+```text
+gravity: detectable (S/N >= 5) down to 25.7 m
+magnetic: never reaches S/N 5; S/N 2.88 even at 0.5 m
+gpr: detectable (S/N >= 5) down to 25.2 m
+```
+
+Pass `threshold=detect.MARGINAL` for the lower threshold, and `search=(shallow, deep)` to bound the sweep.
+Sweep the target size and you have a detection-limit chart; the website draws one at
+[/limits](https://detectability.mukreminnergiz.com/limits).
+
 Target shapes: `sphere`, `horizontal_cylinder`, `vertical_cylinder`, `prism`, `dyke` (any dip) and `contact`. The main
 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.

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

@@ -8,6 +8,7 @@ src/detectability/ert.py
 src/detectability/gpr.py
 src/detectability/gravity.py
 src/detectability/igrf.py
+src/detectability/limits.py
 src/detectability/magnetics.py
 src/detectability/rocks.py
 src/detectability/survey.py
@@ -26,6 +27,7 @@ tests/test_ert_pygimli.py
 tests/test_gpr.py
 tests/test_gravity.py
 tests/test_igrf.py
+tests/test_limits.py
 tests/test_magnetics.py
 tests/test_survey.py
 tests/test_validation.py

detectability-0.6.0/tests/test_limits.py

@@ -0,0 +1,93 @@
+"""The depth limit must agree with the assessment it inverts: detectable just above it, not just below."""
+
+import pytest
+
+from detectability import Target, depth_limit, detect, evaluate
+
+SURVEY = {"latitude": 39.75, "longitude": 37.02, "date": "2026-07-01"}
+CAVITY = {"shape": "sphere", "size": 20, "material": "air", "host": "limestone"}
+
+
+def snr_at(target, depth, method):
+    return evaluate({**target, "depth_top": depth}, SURVEY, methods=[method]).results[0].assessment.snr
+
+
+@pytest.mark.parametrize("method", ["gravity", "gpr"])
+def test_limit_brackets_the_threshold(method):
+    limit = depth_limit(CAVITY, SURVEY, method=method)
+    assert limit.available and limit.depth is not None and not limit.beyond_search
+    assert snr_at(CAVITY, limit.depth * 0.99, method) >= detect.CLEAR
+    assert snr_at(CAVITY, limit.depth * 1.01, method) < detect.CLEAR
+
+
+def test_marginal_reaches_deeper_than_clear():
+    clear = depth_limit(CAVITY, SURVEY, method="gravity")
+    marginal = depth_limit(CAVITY, SURVEY, method="gravity", threshold=detect.MARGINAL)
+    assert marginal.depth > clear.depth
+
+
+def test_a_bigger_body_is_seen_deeper():
+    small = depth_limit({**CAVITY, "size": 10}, SURVEY, method="gravity")
+    large = depth_limit({**CAVITY, "size": 40}, SURVEY, method="gravity")
+    assert large.depth > small.depth
+
+
+def test_depth_top_is_ignored_and_optional():
+    without = depth_limit(CAVITY, SURVEY, method="gravity")
+    with_depth = depth_limit({**CAVITY, "depth_top": 999}, SURVEY, method="gravity")
+    as_object = depth_limit(Target(shape="sphere", depth_top=1, size=20, material="air", host="limestone"),
+                            SURVEY, method="gravity")
+    assert without.depth == pytest.approx(with_depth.depth, rel=1e-9)
+    assert without.depth == pytest.approx(as_object.depth, rel=1e-9)
+
+
+def test_never_detected_reports_the_shallowest_signal():
+    limit = depth_limit(CAVITY, SURVEY, method="magnetic")
+    assert limit.depth is None and limit.available
+    assert 0 < limit.snr_shallowest < detect.CLEAR
+    assert "never reaches" in str(limit)
+
+
+def test_still_detected_at_the_bottom_of_the_search():
+    limit = depth_limit(CAVITY, SURVEY, method="gravity", search=(0.5, 5.0))
+    assert limit.beyond_search and limit.depth == 5.0
+    assert "at least" in str(limit)
+
+
+def test_unassessable_method_says_why():
+    limit = depth_limit({"shape": "sphere", "size": 20, "material": "magnetite", "host": "granite"},
+                        SURVEY, method="gravity")
+    assert not limit.available and limit.depth is None
+    assert "no density for 'magnetite'" in limit.reason and "not assessed" in str(limit)
+
+
+def test_body_keeps_its_thickness_while_it_moves_down():
+    dyke = {"shape": "dyke", "size": 10, "depth_top": 5, "depth_bottom": 45,
+            "material": "air", "host": "limestone"}
+    limit = depth_limit(dyke, SURVEY, method="gravity")
+    assert limit.depth is not None
+    # The 40 m thickness must be kept at the limit, or the answer would be about a different body.
+    assert snr_at({**dyke, "depth_bottom": limit.depth * 0.99 + 40}, limit.depth * 0.99, "gravity") >= detect.CLEAR
+
+
+def test_a_narrow_search_still_lands_on_the_same_answer():
+    wide = depth_limit(CAVITY, SURVEY, method="gravity")
+    narrow = depth_limit(CAVITY, SURVEY, method="gravity", search=(20.0, 30.0), steps=6)
+    assert narrow.depth == pytest.approx(wide.depth, rel=1e-3)
+
+
+@pytest.mark.parametrize("search", [(0, 100), (-1, 10), (100, 10), (10, 10)])
+def test_a_bad_search_range_is_refused(search):
+    with pytest.raises(ValueError, match="search must be"):
+        depth_limit(CAVITY, SURVEY, method="gravity", search=search)
+
+
+def test_too_few_steps_is_refused():
+    with pytest.raises(ValueError, match="steps must be"):
+        depth_limit(CAVITY, SURVEY, method="gravity", steps=1)
+
+
+def test_an_invalid_target_is_refused():
+    with pytest.raises(ValueError):
+        depth_limit({"shape": "sphere", "size": -5, "material": "air", "host": "limestone"},
+                    SURVEY, method="gravity")

detectability-0.5.0/src/detectability/__init__.py

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