ertkit 0.1.0__py3-none-any.whl

ertkit/__init__.py

@@ -0,0 +1,24 @@
+"""ertkit: resistivity inversion for groundwater exploration."""
+
+from __future__ import annotations
+
+import logging
+
+from ertkit._show_versions import show_versions
+from ertkit._warnings import ConvergenceWarning, DataWarning
+from ertkit.noise import ErrorModel
+
+try:
+    from ertkit._version import __version__
+except ImportError:  # pragma: no cover - only when the package is not installed
+    __version__ = "0+unknown"
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "ConvergenceWarning",
+    "DataWarning",
+    "ErrorModel",
+    "__version__",
+    "show_versions",
+]

ertkit/_linalg.py

@@ -0,0 +1,32 @@
+"""Small linear-algebra helpers."""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def matmul(a: NDArray[Any], b: NDArray[Any]) -> NDArray[Any]:
+    """Matrix product that checks its result instead of the floating-point flags.
+
+    With numpy 2.2 and earlier on recent macOS, the Accelerate BLAS can set
+    floating-point flags (divide by zero, overflow) during a matrix product of
+    ordinary finite values, which numpy then reports as spurious warnings. The
+    flags are therefore ignored during the product, and a genuine problem is
+    detected from the result: if finite inputs give a non-finite result, a
+    ``RuntimeWarning`` is raised.
+    """
+    with np.errstate(all="ignore"):
+        out = np.asarray(a @ b)
+    if (
+        not np.all(np.isfinite(out))
+        and np.all(np.isfinite(a))
+        and np.all(np.isfinite(b))
+    ):
+        warnings.warn(
+            "non-finite values in a matrix product", RuntimeWarning, stacklevel=2
+        )
+    return out

ertkit/_show_versions.py

@@ -0,0 +1,49 @@
+"""Report the versions of ertkit, Python and the main dependencies."""
+
+from __future__ import annotations
+
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+_PACKAGES = ("ertkit", "numpy", "scipy", "libdlf", "matplotlib")
+
+
+def _versions() -> dict[str, str]:
+    """Return the versions of Python, the platform and the main packages.
+
+    Returns
+    -------
+    dict of str to str
+        Name to version string; packages that are not installed are reported
+        as ``"not installed"``.
+    """
+    info = {
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+    }
+    for name in _PACKAGES:
+        try:
+            info[name] = version(name)
+        except PackageNotFoundError:
+            info[name] = "not installed"
+    return info
+
+
+def show_versions() -> None:
+    """Print the versions of ertkit, Python and the main dependencies.
+
+    Include this output when you report a problem.
+
+    Examples
+    --------
+    >>> import ertkit
+    >>> ertkit.show_versions()  # doctest: +SKIP
+    python      3.13.16
+    ...
+    """
+    info = _versions()
+    width = max(len(name) for name in info)
+    for name, value in info.items():
+        # Printing is the purpose of this function.
+        print(f"{name:<{width}}  {value}")  # noqa: T201

ertkit/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+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)
+
+__commit_id__ = commit_id = None

ertkit/_warnings.py

@@ -0,0 +1,18 @@
+"""Warning categories raised by ertkit."""
+
+from __future__ import annotations
+
+__all__ = ["ConvergenceWarning", "DataWarning"]
+
+
+class ConvergenceWarning(UserWarning):
+    """An iterative method stopped before meeting its convergence criterion."""
+
+
+class DataWarning(UserWarning):
+    """Data were removed, or the data cannot support a result as requested.
+
+    Raised for removed readings, a poor fit, parameters the data do not
+    resolve, an undetermined depth of investigation, and errors that appear
+    over- or underestimated.
+    """

ertkit/arrays.py

@@ -0,0 +1,71 @@
+"""Electrode configurations and geometric factors.
+
+All distances are in meters. A remote (infinitely distant) electrode is
+given as ``np.inf``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = ["geometric_factor"]
+
+
+def geometric_factor(
+    am: ArrayLike, bm: ArrayLike, an: ArrayLike, bn: ArrayLike
+) -> NDArray[np.float64]:
+    r"""Geometric factor of a four-electrode array on a half-space.
+
+    For current electrodes :math:`A`, :math:`B` and potential electrodes
+    :math:`M`, :math:`N` on the surface of a homogeneous half-space,
+
+    .. math::
+
+        K = \frac{2\pi}{1/AM - 1/BM - 1/AN + 1/BN},
+
+    so that the apparent resistivity is :math:`\rho_a = K \Delta V / I` with
+    :math:`\Delta V = V_M - V_N`.
+
+    Parameters
+    ----------
+    am, bm, an, bn : array_like
+        Distances in meters between the electrodes named by each argument.
+        They broadcast against each other. Use ``np.inf`` for a remote
+        electrode (for example ``bm = bn = np.inf`` for a pole-dipole array).
+
+    Returns
+    -------
+    ndarray of float
+        Geometric factor in meters. It is negative when :math:`V_M < V_N` on a
+        half-space, as in a dipole-dipole array ordered A, B, M, N, where
+        :math:`M` is nearer than :math:`N` to the current sink :math:`B`.
+
+    Raises
+    ------
+    ValueError
+        If a distance is not positive, or if the configuration measures no
+        potential difference on a half-space (zero denominator).
+
+    Examples
+    --------
+    A Wenner array with spacing 10 m:
+
+    >>> import numpy as np
+    >>> from ertkit.arrays import geometric_factor
+    >>> float(geometric_factor(10.0, 20.0, 20.0, 10.0) / (2 * np.pi))
+    10.0
+    """
+    dists = np.broadcast_arrays(
+        *(np.asarray(d, dtype=np.float64) for d in (am, bm, an, bn))
+    )
+    if any(np.any(~(d > 0)) for d in dists):
+        raise ValueError("electrode distances must be positive (np.inf for remote)")
+    d_am, d_bm, d_an, d_bn = dists
+    denom = 1.0 / d_am - 1.0 / d_bm - 1.0 / d_an + 1.0 / d_bn
+    scale = 1.0 / np.minimum.reduce(dists)
+    if np.any(np.abs(denom) <= 1e-12 * scale):
+        raise ValueError(
+            "the configuration measures no potential difference on a half-space"
+        )
+    return np.asarray(2.0 * np.pi / denom, dtype=np.float64)

ertkit/noise.py

@@ -0,0 +1,134 @@
+"""Measurement-error models."""
+
+from __future__ import annotations
+
+import math
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ertkit._warnings import DataWarning
+
+__all__ = ["ErrorModel"]
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class ErrorModel:
+    r"""Standard deviation of measurement errors on the transfer resistance.
+
+    Errors are specified on the transfer resistance :math:`R = \Delta V / I`
+    (LaBrecque et al. 1996) as
+
+    .. math::
+
+        s_R = a + b \, |R|,
+
+    with an absolute part :math:`a` in ohms (voltage noise) and a relative part
+    :math:`b`. Since apparent resistivity is :math:`\rho_a = K R`, the data
+    :math:`d = \ln \rho_a` have log-space standard deviation
+    :math:`s = b + a / |R|`.
+
+    Parameters
+    ----------
+    relative : float, optional
+        Relative part :math:`b`, as a fraction: 0.03 means 3%. The default,
+        0.03, is a common choice; 2 to 5% is typical, and up to 10% where the
+        earth is far from layered. It should include a floor for modeling
+        errors: reciprocal or repeated readings (Tso et al. 2017) measure the
+        noise only, so they do not justify a value below about 2%.
+    absolute : float, optional
+        Absolute part :math:`a`, in ohms: about the voltage noise divided by
+        the current. Default 0.
+
+    Raises
+    ------
+    ValueError
+        If a part is negative or not finite, or if both are zero.
+
+    Warns
+    -----
+    DataWarning
+        If ``relative`` is above 0.5, which suggests a percentage given where
+        a fraction is expected.
+
+    Examples
+    --------
+    >>> from ertkit import ErrorModel
+    >>> noise = ErrorModel(relative=0.03, absolute=1e-4)
+    >>> round(float(noise.log_std(0.01)[0]), 6)
+    0.04
+    """
+
+    relative: float = 0.03
+    absolute: float = 0.0
+
+    def __post_init__(self) -> None:
+        for name in ("relative", "absolute"):
+            value = getattr(self, name)
+            if not (math.isfinite(value) and value >= 0):
+                raise ValueError(f"{name} error must be finite and non-negative")
+        if self.relative == 0 and self.absolute == 0:
+            raise ValueError("at least one of relative and absolute must be positive")
+        if self.relative > 0.5:
+            warnings.warn(
+                f"relative error {self.relative:g} is {100 * self.relative:g}%; "
+                "it is a fraction: 0.03 means 3%",
+                DataWarning,
+                stacklevel=3,
+            )
+        object.__setattr__(self, "relative", float(self.relative))
+        object.__setattr__(self, "absolute", float(self.absolute))
+
+    def resistance_std(self, resistance: ArrayLike) -> NDArray[np.float64]:
+        r"""Standard deviation :math:`s_R = a + b|R|` of transfer resistances.
+
+        Parameters
+        ----------
+        resistance : array_like
+            Transfer resistances :math:`R` in ohms.
+
+        Returns
+        -------
+        ndarray of float
+            Standard deviations in ohms.
+        """
+        r = np.atleast_1d(np.asarray(resistance, dtype=np.float64))
+        return self.absolute + self.relative * np.abs(r)
+
+    def log_std(self, resistance: ArrayLike) -> NDArray[np.float64]:
+        r"""Standard deviation :math:`s = b + a/|R|` of :math:`\ln \rho_a`.
+
+        Parameters
+        ----------
+        resistance : array_like
+            Transfer resistances :math:`R` in ohms.
+
+        Returns
+        -------
+        ndarray of float
+            Standard deviations of the natural logarithm of the data.
+        """
+        r = np.atleast_1d(np.asarray(resistance, dtype=np.float64))
+        return np.asarray(self.relative + self.absolute / np.abs(r), dtype=np.float64)
+
+    def usable(self, resistance: ArrayLike) -> NDArray[np.bool_]:
+        """Readings that can be inverted in log space.
+
+        A reading is usable when :math:`R > 0` and, if there is an absolute
+        part, :math:`|R| \\ge 3a`; below that the logarithm is dominated by
+        noise.
+
+        Parameters
+        ----------
+        resistance : array_like
+            Transfer resistances :math:`R` in ohms.
+
+        Returns
+        -------
+        ndarray of bool
+            True for each usable reading.
+        """
+        r = np.atleast_1d(np.asarray(resistance, dtype=np.float64))
+        return np.asarray(np.isfinite(r) & (r > 0) & (np.abs(r) >= 3.0 * self.absolute))

ertkit/plot/__init__.py

@@ -0,0 +1,19 @@
+"""Plots of soundings and layered models.
+
+Needs matplotlib, which the ``plot`` extra installs::
+
+    pip install "ertkit[plot]"
+"""
+
+from __future__ import annotations
+
+try:
+    import matplotlib  # noqa: F401
+except ImportError as exc:  # pragma: no cover - exercised in a subprocess test
+    raise ImportError(
+        'ertkit.plot needs matplotlib; install it with: pip install "ertkit[plot]"'
+    ) from exc
+
+from ertkit.plot._ves import layered_model, sounding
+
+__all__ = ["layered_model", "sounding"]

ertkit/plot/_ves.py

@@ -0,0 +1,234 @@
+"""Plots for vertical electrical soundings."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ertkit.results import InversionResult
+from ertkit.ves.data import Sounding
+from ertkit.ves.invert import LayerFit, _segments
+from ertkit.ves.model import LayeredModel
+from ertkit.ves.smooth import DOI_THRESHOLD, SmoothFit
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+
+__all__ = ["layered_model", "sounding"]
+
+_MAX_FACTOR = 100.0
+"""Resistivity error bars are drawn to at most this factor either side."""
+
+
+def _axes(ax: Axes | None) -> Axes:
+    if ax is not None:
+        return ax
+    import matplotlib.pyplot as plt
+
+    _, new = plt.subplots(figsize=(6.0, 4.5), layout="constrained")
+    return new
+
+
+def sounding(
+    data: Sounding,
+    *fits: InversionResult,
+    labels: Sequence[str] | None = None,
+    ax: Axes | None = None,
+) -> Axes:
+    """Plot apparent resistivity against AB/2, with the data errors and fitted curves.
+
+    Fitted curves are drawn separately for each MN segment (readings with the
+    same MN/2), so that static shifts between segments show as steps. When
+    MN changes with every reading, as in a Wenner sounding, one curve is drawn.
+
+    Parameters
+    ----------
+    data : Sounding
+        The observed data; error bars show one standard deviation.
+    *fits : InversionResult
+        Inversion results whose predicted data are drawn as lines.
+    labels : sequence of str, optional
+        One label per fit. Default "fit 1", "fit 2", and so on.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is made if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    ax = _axes(ax)
+    ab2, rhoa, s = data.survey.ab2, data.rhoa, data.log_std
+    yerr = np.vstack([rhoa * (1.0 - np.exp(-s)), rhoa * (np.exp(s) - 1.0)])
+    ax.errorbar(ab2, rhoa, yerr=yerr, fmt="o", ms=4, color="black", label="data")
+    labels = (
+        [f"fit {i + 1}" for i in range(len(fits))] if labels is None else list(labels)
+    )
+    segment = _segments(data.survey.mn2)
+    if np.bincount(segment).max() < 2:
+        segment = np.zeros_like(segment)
+    for fit, label in zip(fits, labels, strict=True):
+        color = None
+        for k in np.unique(segment):
+            # Readings of one MN segment, in order of AB/2.
+            sel = np.flatnonzero(segment == k)
+            sel = sel[np.argsort(ab2[sel], kind="stable")]
+            (line,) = ax.plot(
+                ab2[sel],
+                fit.predicted[sel],
+                color=color,
+                label=label if k == segment[0] else None,
+            )
+            color = line.get_color()
+    ax.set_xscale("log")
+    ax.set_yscale("log")
+    ax.set_xlabel("AB/2 (m)")
+    ax.set_ylabel(r"apparent resistivity ($\Omega$ m)")
+    ax.grid(True, which="both", alpha=0.3)
+    ax.legend()
+    return ax
+
+
+def _steps(
+    model: LayeredModel, depth_max: float, depth_min: float = 0.0
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Resistivity and depth arrays for a step plot from depth_min to depth_max."""
+    tops = np.concatenate([[depth_min], model.depths])
+    bottoms = np.concatenate([model.depths, [max(depth_max, tops[-1])]])
+    depth = np.ravel(np.column_stack([tops, bottoms]))
+    rho = np.repeat(model.resistivity, 2)
+    return rho, depth
+
+
+def _default_depth_max(
+    items: Sequence[LayeredModel | LayerFit | SmoothFit], models: list[LayeredModel]
+) -> float:
+    """1.5 times the deepest depth of investigation, else the deepest interface."""
+    dois = [
+        item.doi
+        for item in items
+        if isinstance(item, SmoothFit) and np.isfinite(item.doi) and item.doi > 0
+    ]
+    interfaces = [
+        float(m.depths[-1])
+        for item, m in zip(items, models, strict=True)
+        if m.depths.size and not isinstance(item, SmoothFit)
+    ]
+    return 1.5 * max(dois or interfaces or [10.0])
+
+
+def layered_model(
+    *items: LayeredModel | LayerFit | SmoothFit,
+    labels: Sequence[str] | None = None,
+    depth_max: float | None = None,
+    log_depth: bool = False,
+    ax: Axes | None = None,
+) -> Axes:
+    """Plot layered models as resistivity against depth.
+
+    Few-layer fits show one standard deviation of each layer's resistivity
+    and of each interface depth; error bars are cut at the edges of the plot,
+    and resistivity error bars at a factor of 100 (``LayerFit.factor`` gives
+    the values). Smooth fits shade the region below their depth of
+    investigation, where the model reflects the regularization rather than the
+    data.
+
+    Parameters
+    ----------
+    *items : LayeredModel, LayerFit or SmoothFit
+        Models, or inversion results whose models are drawn.
+    labels : sequence of str, optional
+        One label per item. Default "model 1", "model 2", and so on.
+    depth_max : float, optional
+        Deepest depth shown, in meters. Default: 1.5 times the depth of
+        investigation of the smooth fits, or else 1.5 times the deepest
+        interface.
+    log_depth : bool, optional
+        Use a logarithmic depth axis, which suits smooth models whose layers
+        thicken with depth. Default False.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw on; a new figure is made if omitted.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+    """
+    ax = _axes(ax)
+    labels = (
+        [f"model {i + 1}" for i in range(len(items))]
+        if labels is None
+        else list(labels)
+    )
+    models = [item if isinstance(item, LayeredModel) else item.model for item in items]
+    if depth_max is None:
+        depth_max = _default_depth_max(items, models)
+    shallowest = [float(m.depths[0]) for m in models if m.depths.size]
+    depth_min = 0.5 * min(shallowest, default=1.0) if log_depth else 0.0
+    for item, model, label in zip(items, models, labels, strict=True):
+        rho, depth = _steps(model, depth_max, depth_min)
+        (line,) = ax.plot(rho, depth, label=label)
+        if isinstance(item, LayerFit):
+            n = model.n_layers
+            tops = np.concatenate([[depth_min], model.depths])
+            bottoms = np.concatenate([model.depths, [depth_max]])
+            mid = np.sqrt(tops * bottoms) if log_depth else 0.5 * (tops + bottoms)
+            factor = np.minimum(item.factor[:n], _MAX_FACTOR)
+            ax.errorbar(
+                model.resistivity,
+                mid,
+                xerr=[
+                    model.resistivity * (1 - 1 / factor),
+                    model.resistivity * (factor - 1),
+                ],
+                fmt="none",
+                color=line.get_color(),
+                capsize=3,
+            )
+            if n > 1:
+                ax.errorbar(
+                    np.sqrt(model.resistivity[:-1] * model.resistivity[1:]),
+                    model.depths,
+                    # Error bars stop at the edges of the plot.
+                    yerr=[
+                        np.minimum(item.depth_std, model.depths - depth_min).clip(0),
+                        np.minimum(item.depth_std, depth_max - model.depths).clip(0),
+                    ],
+                    fmt="none",
+                    color=line.get_color(),
+                    capsize=3,
+                )
+        if (
+            isinstance(item, SmoothFit)
+            and np.isfinite(item.doi)
+            and item.doi < depth_max
+        ):
+            ax.axhspan(
+                max(item.doi, depth_min),
+                depth_max,
+                color=line.get_color(),
+                alpha=0.12,
+                label=f"below depth of investigation ({label})",
+            )
+            # Isolated layers above the depth of investigation whose index
+            # also reaches the threshold are unresolved too.
+            tops = np.concatenate([[0.0], model.depths])
+            bottoms = np.concatenate([model.depths, [depth_max]])
+            for j in np.flatnonzero(item.doi_index >= DOI_THRESHOLD):
+                if bottoms[j] <= item.doi:
+                    ax.axhspan(
+                        max(tops[j], depth_min),
+                        bottoms[j],
+                        color=line.get_color(),
+                        alpha=0.12,
+                    )
+    ax.set_xscale("log")
+    if log_depth:
+        ax.set_yscale("log")
+    ax.set_ylim(depth_max, depth_min)
+    ax.set_xlabel(r"resistivity ($\Omega$ m)")
+    ax.set_ylabel("depth (m)")
+    ax.grid(True, which="both", alpha=0.3)
+    ax.legend()
+    return ax

ertkit/results.py

@@ -0,0 +1,82 @@
+"""Result objects shared by the inversion methods."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = ["InversionResult"]
+
+
+@dataclass(frozen=True, eq=False, kw_only=True, slots=True)
+class InversionResult:
+    r"""Common part of every inversion result.
+
+    Results are immutable: their arrays are read-only.
+
+    Attributes
+    ----------
+    predicted : ndarray
+        Data predicted by the final model (apparent resistivity, ohm meters).
+    residuals : ndarray
+        Normalized residuals :math:`(d_i - f_i)/s_i` of the log data, one per
+        reading; their squares sum to ``chi2``. For a fit to the noise level
+        they scatter around 0 with a spread of about 1, without trends.
+    chi2 : float
+        Final misfit :math:`\chi^2` of the log data.
+    chi2_target : float
+        The misfit the method aimed at: :math:`N_d - p`, the value expected
+        for a fit with :math:`p` free parameters that matches the data to
+        their errors; :math:`N_d` for a smooth inversion, or 1.1 times the
+        smallest misfit when :math:`N_d` cannot be reached.
+    n_data : int
+        Number of data :math:`N_d`.
+    converged : bool
+        Whether the method met its convergence criterion.
+    stop_reason : str
+        Why the iteration stopped.
+    n_iterations : int
+        Number of iterations (or function evaluations, for methods that count
+        those).
+    """
+
+    predicted: NDArray[np.float64]
+    residuals: NDArray[np.float64]
+    chi2: float
+    chi2_target: float
+    n_data: int
+    converged: bool
+    stop_reason: str
+    n_iterations: int
+
+    def __post_init__(self) -> None:
+        for f in fields(self):
+            value = getattr(self, f.name)
+            if isinstance(value, np.ndarray):
+                value.setflags(write=False)
+
+    @property
+    def chi2_ratio(self) -> float:
+        r""":math:`\chi^2` divided by its target; about 1 for a fit to the noise level."""
+        return float(self.chi2 / self.chi2_target)
+
+    def summary(self) -> str:
+        """Readable summary of the fit and the model.
+
+        Uncertainty factors are written ``x/ f``: the value multiplied or
+        divided by ``f``.
+        """
+        lines = [
+            (
+                f"{type(self).__name__}: chi2 = {self.chi2:.4g} for {self.n_data} data "
+                f"(target {self.chi2_target:.4g}, ratio {self.chi2_ratio:.3g})"
+            ),
+            f"converged: {self.converged} ({self.stop_reason})",
+        ]
+        return "\n".join(lines + self._details())
+
+    def _details(self) -> list[str]:
+        """Method-specific lines of the summary."""
+        return []