ertkit 0.1.0__tar.gz → 0.1.1__tar.gz

{ertkit-0.1.0 → ertkit-0.1.1}/.pre-commit-config.yaml

@@ -21,19 +21,19 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.17.0
+    rev: v0.17.4
     hooks:
       - id: ruff-check
         args: [--fix, --show-fixes, --exit-non-zero-on-fix]
       - id: ruff-format
 
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.25
+    rev: v0.27
     hooks:
       - id: validate-pyproject
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.38.2
+    rev: 0.39.0
     hooks:
       - id: check-github-workflows
       - id: check-dependabot
@@ -52,6 +52,6 @@ repos:
       - id: rst-inline-touching-normal
 
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: v1.30.1
+    rev: v1.32.0
     hooks:
       - id: zizmor

{ertkit-0.1.0 → ertkit-0.1.1}/CHANGELOG.md

@@ -6,6 +6,28 @@ project uses [semantic versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-11-09
+
+### Added
+
+- The Zenodo DOI in `CITATION.cff`, the README and the documentation, and a
+  `Citation` link in the package metadata.
+
+### Fixed
+
+- Synthetic soundings screen noise-free readings before adding log-space
+  noise, preventing signals below the noise floor from becoming enormous
+  accepted readings or overflowing. Noisy readings are screened again.
+- Smooth inversion preserves the stopping reason after relaxing the misfit
+  target, rather than claiming the target was matched when the smoothest
+  model already fits better or the relaxed target remains unreachable.
+- Smooth inversion requires at least three layers to span both endpoints of
+  `depth_range`. Two-layer fitting remains available with `invert_few_layer`.
+
+### Changed
+
+- Updated pre-commit hook versions as part of the release checklist.
+
 ## [0.1.0] - 2026-10-15
 
 ### Added
@@ -80,5 +102,6 @@ project uses [semantic versioning](https://semver.org/).
   recorded in a verification report (`pytest -m verification
   --verification-report=PATH`).
 
-[Unreleased]: https://github.com/abdgafartunde/ertkit/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/abdgafartunde/ertkit/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/abdgafartunde/ertkit/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/abdgafartunde/ertkit/releases/tag/v0.1.0

{ertkit-0.1.0 → ertkit-0.1.1}/CITATION.cff

@@ -7,8 +7,16 @@ authors:
     given-names: "Abd'gafar Tunde"
     orcid: "https://orcid.org/0000-0003-1641-7196"
     affiliation: "School of Mathematics, Jilin University"
-version: "0.1.0"
-date-released: "2026-10-15"
+version: "0.1.1"
+date-released: "2026-11-09"
+doi: 10.5281/zenodo.23385097
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.23385097
+    description: "Concept DOI: all versions, resolving to the latest"
+  - type: doi
+    value: 10.5281/zenodo.23385098
+    description: "Version 0.1.0"
 license: MIT
 repository-code: "https://github.com/abdgafartunde/ertkit"
 url: "https://abdgafartunde.github.io/ertkit/"

{ertkit-0.1.0 → ertkit-0.1.1}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: ertkit
-Version: 0.1.0
+Version: 0.1.1
 Summary: Resistivity inversion for groundwater exploration (VES now, 2.5-D ERT planned), with uncertainty and depth of investigation.
 Project-URL: Documentation, https://abdgafartunde.github.io/ertkit/
 Project-URL: Source, https://github.com/abdgafartunde/ertkit
 Project-URL: Issues, https://github.com/abdgafartunde/ertkit/issues
 Project-URL: Changelog, https://github.com/abdgafartunde/ertkit/blob/main/CHANGELOG.md
+Project-URL: Citation, https://doi.org/10.5281/zenodo.23385097
 Author: Abd'gafar Tunde Tiamiyu
 License-Expression: MIT
 License-File: LICENSE
@@ -37,6 +38,7 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/abdgafartunde/ertkit/actions/workflows/ci.yml/badge.svg)](https://github.com/abdgafartunde/ertkit/actions/workflows/ci.yml)
 [![Docs](https://github.com/abdgafartunde/ertkit/actions/workflows/docs.yml/badge.svg)](https://abdgafartunde.github.io/ertkit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abdgafartunde/ertkit/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23385097.svg)](https://doi.org/10.5281/zenodo.23385097)
 
 **Resistivity imaging for groundwater exploration, with an honest account of
 what the data can resolve.**
@@ -107,10 +109,12 @@ deviation).
 
 ## Status
 
-Release 0.1 covers vertical electrical sounding: a layered-earth forward
+Release 0.1.1 covers vertical electrical sounding: a layered-earth forward
 model, few-layer inversion with linearized uncertainty, smooth inversion with
-sensitivity and a depth of investigation, CSV input and plotting. Planned
-releases:
+sensitivity and a depth of investigation, CSV input and plotting. This patch
+screens weak synthetic signals before adding noise, corrects smooth-inversion
+stopping summaries, and requires at least three layers for a smooth grid.
+Two-layer fitting remains available through `invert_few_layer`. Planned releases:
 
 | Release | Content |
 |---|---|
@@ -147,7 +151,9 @@ and the [Code of Conduct](https://github.com/abdgafartunde/ertkit/blob/main/CODE
 
 ## Citing
 
-Each release is archived on Zenodo with a DOI. Citation metadata are in
+Each release is archived on Zenodo with a DOI; to cite ertkit in general, use
+the concept DOI [10.5281/zenodo.23385097](https://doi.org/10.5281/zenodo.23385097),
+which always resolves to the latest version. Citation metadata are in
 [CITATION.cff](https://github.com/abdgafartunde/ertkit/blob/main/CITATION.cff);
 please also cite the methods ertkit implements.
 

{ertkit-0.1.0 → ertkit-0.1.1}/README.md

@@ -4,6 +4,7 @@
 [![CI](https://github.com/abdgafartunde/ertkit/actions/workflows/ci.yml/badge.svg)](https://github.com/abdgafartunde/ertkit/actions/workflows/ci.yml)
 [![Docs](https://github.com/abdgafartunde/ertkit/actions/workflows/docs.yml/badge.svg)](https://abdgafartunde.github.io/ertkit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abdgafartunde/ertkit/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23385097.svg)](https://doi.org/10.5281/zenodo.23385097)
 
 **Resistivity imaging for groundwater exploration, with an honest account of
 what the data can resolve.**
@@ -74,10 +75,12 @@ deviation).
 
 ## Status
 
-Release 0.1 covers vertical electrical sounding: a layered-earth forward
+Release 0.1.1 covers vertical electrical sounding: a layered-earth forward
 model, few-layer inversion with linearized uncertainty, smooth inversion with
-sensitivity and a depth of investigation, CSV input and plotting. Planned
-releases:
+sensitivity and a depth of investigation, CSV input and plotting. This patch
+screens weak synthetic signals before adding noise, corrects smooth-inversion
+stopping summaries, and requires at least three layers for a smooth grid.
+Two-layer fitting remains available through `invert_few_layer`. Planned releases:
 
 | Release | Content |
 |---|---|
@@ -114,7 +117,9 @@ and the [Code of Conduct](https://github.com/abdgafartunde/ertkit/blob/main/CODE
 
 ## Citing
 
-Each release is archived on Zenodo with a DOI. Citation metadata are in
+Each release is archived on Zenodo with a DOI; to cite ertkit in general, use
+the concept DOI [10.5281/zenodo.23385097](https://doi.org/10.5281/zenodo.23385097),
+which always resolves to the latest version. Citation metadata are in
 [CITATION.cff](https://github.com/abdgafartunde/ertkit/blob/main/CITATION.cff);
 please also cite the methods ertkit implements.
 

ertkit-0.1.1/docs/citing.md

@@ -0,0 +1,17 @@
+# Citing ertkit
+
+Each release of ertkit is archived on Zenodo, which issues a DOI for every
+version and a concept DOI that always resolves to the latest version:
+
+- all versions (concept DOI):
+  [10.5281/zenodo.23385097](https://doi.org/10.5281/zenodo.23385097)
+- version 0.1.0:
+  [10.5281/zenodo.23385098](https://doi.org/10.5281/zenodo.23385098)
+
+To make results reproducible, cite the version you used. The citation
+metadata are in
+[CITATION.cff](https://github.com/abdgafartunde/ertkit/blob/main/CITATION.cff),
+from which GitHub offers APA and BibTeX entries ("Cite this repository").
+
+Please also cite the methods ertkit implements; the references are listed in
+the [user guide](user_guide/ves.md#references).

{ertkit-0.1.0 → ertkit-0.1.1}/docs/user_guide/ves.md

@@ -87,6 +87,10 @@ $$
 
 A {class}`~ertkit.ves.Sounding` removes readings that cannot be inverted in
 log space ($R \le 0$, or $|R|$ below three times $a$) and warns about them.
+{meth}`~ertkit.ves.Sounding.synthetic` screens the noise-free readings before
+drawing noise, then screens the noisy readings again. A weak signal cannot
+become an accepted reading just because a large log-space noise draw amplified
+it. If no reading is usable, it raises `ValueError`.
 
 ## Few-layer inversion
 
@@ -162,8 +166,16 @@ Constable et al. 1987): the regularization weight $\mu$ is the largest with
 $\chi^2 = N_d$. If even the smoothest model fits better than that, ertkit
 reports it and warns that the errors may be overestimated. If no model reaches
 $\chi^2 = N_d$, which happens for a few percent of soundings even with correct
-errors, the inversion fits 1.1 times the smallest misfit instead (recorded in
-`chi2_target`), and warns only when that misfit is improbably large.
+errors, the inversion targets 1.1 times the smallest misfit instead (recorded
+in `chi2_target`), and warns about a poor fit only when the smallest misfit is
+improbably large. The `stop_reason` distinguishes reaching the relaxed target
+from finding that the smoothest model already fits better, or that the target
+remains unreachable.
+
+The smooth grid requires at least three layers, including the bottom
+half-space, so that its first and last interfaces span `depth_range`. For a
+two-layer fit with an estimated interface depth, use
+{func}`~ertkit.ves.invert_few_layer` with `n_layers=2`.
 
 The result, a {class}`~ertkit.ves.SmoothFit`, includes:
 

{ertkit-0.1.0 → ertkit-0.1.1}/pyproject.toml

@@ -51,6 +51,7 @@ Documentation = "https://abdgafartunde.github.io/ertkit/"
 Source = "https://github.com/abdgafartunde/ertkit"
 Issues = "https://github.com/abdgafartunde/ertkit/issues"
 Changelog = "https://github.com/abdgafartunde/ertkit/blob/main/CHANGELOG.md"
+Citation = "https://doi.org/10.5281/zenodo.23385097"
 
 [dependency-groups]
 test = [

{ertkit-0.1.0 → ertkit-0.1.1}/src/ertkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
 
 __commit_id__ = commit_id = None

{ertkit-0.1.0 → ertkit-0.1.1}/src/ertkit/ves/data.py

@@ -121,7 +121,9 @@ class Sounding:
         Noise is drawn from the error model in log space:
         :math:`\ln \rho_a^{\mathrm{obs}} = \ln \rho_a + s \, \varepsilon`, with
         :math:`\varepsilon \sim N(0, 1)` and :math:`s` evaluated at the
-        noise-free data.
+        noise-free data. Unusable noise-free readings are removed before
+        drawing noise, so a signal below the noise floor cannot be amplified
+        into a usable reading. Noisy readings are screened again afterwards.
 
         Parameters
         ----------
@@ -138,13 +140,23 @@ class Sounding:
         Returns
         -------
         Sounding
+
+        Raises
+        ------
+        ValueError
+            If no noise-free or noisy reading is usable.
+
+        Warns
+        -----
+        DataWarning
+            If noise-free or noisy readings are removed.
         """
         error = ErrorModel() if error is None else error
         generator = np.random.default_rng(rng)
-        clean = forward(model, survey)
-        s = error.log_std(clean / survey.geometric_factor)
-        noisy = clean * np.exp(s * generator.standard_normal(clean.size))
-        return cls(survey=survey, rhoa=noisy, error=error)
+        clean = cls(survey=survey, rhoa=forward(model, survey), error=error)
+        s = error.log_std(clean.resistance)
+        noisy = clean.rhoa * np.exp(s * generator.standard_normal(clean.n_data))
+        return cls(survey=clean.survey, rhoa=noisy, error=error)
 
     @property
     def n_data(self) -> int:

{ertkit-0.1.0 → ertkit-0.1.1}/src/ertkit/ves/smooth.py

@@ -385,7 +385,9 @@ def invert_smooth(
     data : Sounding
         The data and their error model.
     n_layers : int, optional
-        Number of layers, including the bottom half-space. Default 30.
+        Number of layers, including the bottom half-space. At least 3, so
+        that distinct first and last interfaces span ``depth_range``.
+        Default 30. Use :func:`~ertkit.ves.invert_few_layer` for a two-layer fit.
     depth_range : (float, float), optional
         Depths in meters of the first and last layer interfaces, which are
         spaced logarithmically. Default: 0.3 times the smallest and 3 times
@@ -405,7 +407,7 @@ def invert_smooth(
     TypeError
         If ``data`` is not a :class:`Sounding`.
     ValueError
-        If ``n_layers`` is less than 2, ``max_iter`` is less than 1, or
+        If ``n_layers`` is less than 3, ``max_iter`` is less than 1, or
         ``depth_range`` is invalid.
 
     Warns
@@ -424,9 +426,11 @@ def invert_smooth(
     -----
     The method is Occam's inversion (Constable et al. 1987). If no model
     reaches :math:`\chi^2 = N_d` (which happens for a few percent of soundings
-    even with correct errors), the inversion fits 1.1 times the smallest
-    misfit instead, recorded in ``chi2_target`` and ``stop_reason``, and warns
-    only if that misfit is improbably large.
+    even with correct errors), the inversion targets 1.1 times the smallest
+    misfit instead, recorded in ``chi2_target``. The ``stop_reason`` says
+    whether this relaxed target was reached, the smoothest model already fits
+    better, or the target remains unreachable. A poor-fit warning is issued
+    only if the smallest misfit is improbably large.
 
     The depth of investigation follows Oldenburg and Li (1999), with reference
     models of 0.1 and 10 times the geometric mean apparent resistivity (a
@@ -448,8 +452,11 @@ def invert_smooth(
         raise TypeError(f"data must be a Sounding, got {type(data_obj).__name__}")
     n_layers = operator.index(n_layers)
     max_iter = operator.index(max_iter)
-    if n_layers < 2:
-        raise ValueError("a smooth model needs at least 2 layers")
+    if n_layers < 3:
+        raise ValueError(
+            "a smooth model needs at least 3 layers to span depth_range; "
+            "use invert_few_layer for a two-layer fit"
+        )
     if max_iter < 1:
         raise ValueError("max_iter must be at least 1")
     thickness = _layer_thicknesses(data, n_layers, depth_range)
@@ -466,7 +473,11 @@ def invert_smooth(
             start, max_iter, target=target
         )
         n_iter += refit_iter
-        reason = _TARGET_RELAXED if converged else refit_reason
+        reason = (
+            _TARGET_RELAXED
+            if converged and refit_reason == _TARGET_REACHED
+            else f"chi2 = N_d cannot be reached; relaxed target: {refit_reason}"
+        )
         if stats.chi2.sf(chi2_min, data.n_data) < _POOR_FIT_P_VALUE:
             n_segments = int(_segments(data.survey.mn2).max()) + 1
             warnings.warn(

{ertkit-0.1.0 → ertkit-0.1.1}/tests/ves/test_data.py

@@ -26,6 +26,32 @@ class TestSounding:
         b = Sounding.synthetic(MODEL, SURVEY, rng=np.random.default_rng(7))
         np.testing.assert_array_equal(a.rhoa, b.rhoa)
 
+    def test_synthetic_screens_weak_signals_before_drawing_noise(self) -> None:
+        # Long spacings have negligible transfer resistance. Log-space noise
+        # must not amplify them into apparently usable, enormous readings.
+        model = LayeredModel(resistivity=[100.0], thickness=[])
+        survey = Survey.schlumberger(ab2=np.geomspace(2.5, 1e6, 30), mn2=0.5)
+        error = ErrorModel(relative=0.03, absolute=1e-4)
+        clean = forward(model, survey)
+        usable = error.usable(clean / survey.geometric_factor)
+        assert usable.any()
+        assert not usable.all()
+        with pytest.warns(DataWarning, match="removed"):
+            data = Sounding.synthetic(model, survey, error, rng=0)
+        assert np.isin(data.survey.ab2, survey.ab2[usable]).all()
+        assert np.all(np.isfinite(data.rhoa))
+        # A loose bound for this fixed noise draw around 100 ohm m; the
+        # regression produced enormous outliers (and eventually overflow).
+        assert data.rhoa.max() < 1000.0
+
+    def test_synthetic_rejects_a_survey_entirely_below_the_noise_floor(self) -> None:
+        model = LayeredModel(resistivity=[100.0], thickness=[])
+        survey = Survey.schlumberger(ab2=[1e4, 1e5], mn2=0.5)
+        with pytest.raises(ValueError, match="no reading is usable"):
+            Sounding.synthetic(
+                model, survey, ErrorModel(relative=0.03, absolute=1e-4), rng=0
+            )
+
     def test_synthetic_noise_has_the_stated_distribution(self) -> None:
         # 2000 soundings of 22 readings: the standardized log residuals should
         # have mean 0 and standard deviation 1. With 44,000 draws the standard

{ertkit-0.1.0 → ertkit-0.1.1}/tests/ves/test_invert_smooth.py

@@ -267,6 +267,23 @@ def test_unreachable_target_with_correct_errors_is_not_a_poor_fit() -> None:
     assert np.isfinite(result.doi)
 
 
+def test_relaxed_target_preserves_the_smoothest_model_stop_reason() -> None:
+    # This coarse grid cannot fit the three-layer earth. After relaxation,
+    # even the smoothest model lies below the new target; it has converged,
+    # but must not claim to have matched that target.
+    survey = Survey.schlumberger(ab2=np.geomspace(2.5, 200.0, 22), mn2=0.5)
+    data = Sounding.synthetic(README_MODEL, survey, NOISE, rng=0)
+    with pytest.warns(DataWarning, match="poor fit"):
+        result = invert_smooth(data, n_layers=3, depth_of_investigation=False)
+    assert result.converged
+    assert result.chi2 < 0.99 * result.chi2_target
+    assert "relaxed target" in result.stop_reason
+    assert (
+        "the smoothest model fits better than the target misfit" in result.stop_reason
+    )
+    assert result.stop_reason != _TARGET_RELAXED
+
+
 @pytest.mark.filterwarnings("ignore:poor fit:ertkit.DataWarning")
 def test_extreme_data_do_not_overflow() -> None:
     # A contrast of 1e4 with 20% noise reported as 0.5%, on 80 layers: before
@@ -305,7 +322,10 @@ def test_too_few_iterations_warns() -> None:
 @pytest.mark.parametrize(
     ("kwargs", "match"),
     [
-        ({"n_layers": 1}, "at least 2 layers"),
+        ({"n_layers": 1}, "at least 3 layers"),
+        ({"n_layers": 2}, "at least 3 layers"),
+        ({"n_layers": 2, "depth_range": (1.0, 100.0)}, "at least 3 layers"),
+        ({"n_layers": 2, "depth_range": (1.0, 1000.0)}, "at least 3 layers"),
         ({"max_iter": 0}, "max_iter must be at least 1"),
         ({"depth_range": (5.0, 1.0)}, "0 < top < bottom"),
         ({"depth_range": (0.0, 10.0)}, "0 < top < bottom"),

ertkit-0.1.0/docs/citing.md

@@ -1,9 +0,0 @@
-# Citing ertkit
-
-Each release of ertkit is archived on Zenodo, which issues a DOI for every
-version and a concept DOI that always resolves to the latest version. The
-citation metadata are in
-[CITATION.cff](https://github.com/abdgafartunde/ertkit/blob/main/CITATION.cff).
-
-Please also cite the methods ertkit implements; the references are listed in
-the [user guide](user_guide/ves.md#references).