ertkit 0.1.0__py3-none-any.whl

ertkit/ves/__init__.py

@@ -0,0 +1,28 @@
+"""Vertical electrical sounding (VES): layered-earth modeling and inversion."""
+
+from __future__ import annotations
+
+from ertkit.ves.data import Sounding
+from ertkit.ves.forward import forward, hankel_j0, potential, resistivity_transform
+from ertkit.ves.invert import LayerFit, invert_few_layer
+from ertkit.ves.io import read_csv, write_csv
+from ertkit.ves.model import LayeredModel
+from ertkit.ves.smooth import DOI_THRESHOLD, SmoothFit, invert_smooth
+from ertkit.ves.survey import Survey
+
+__all__ = [
+    "DOI_THRESHOLD",
+    "LayerFit",
+    "LayeredModel",
+    "SmoothFit",
+    "Sounding",
+    "Survey",
+    "forward",
+    "hankel_j0",
+    "invert_few_layer",
+    "invert_smooth",
+    "potential",
+    "read_csv",
+    "resistivity_transform",
+    "write_csv",
+]

ertkit/ves/data.py

@@ -0,0 +1,167 @@
+"""Observed or synthetic VES data."""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ertkit._warnings import DataWarning
+from ertkit.noise import ErrorModel
+from ertkit.ves.forward import forward
+from ertkit.ves.model import LayeredModel
+from ertkit.ves.survey import Survey
+
+__all__ = ["Sounding"]
+
+
+@dataclass(frozen=True, eq=False, kw_only=True, slots=True)
+class Sounding:
+    r"""Apparent resistivities of a sounding with their error model.
+
+    Readings that cannot be inverted in log space (transfer resistance
+    :math:`R \le 0`, or :math:`|R|` below three times the absolute error) are
+    removed with a :class:`~ertkit.DataWarning`.
+
+    Parameters
+    ----------
+    survey : Survey
+        Electrode half-spacings of the readings.
+    rhoa : array_like
+        Apparent resistivity in ohm meters, one value per reading.
+    error : ErrorModel or None, optional
+        Measurement-error model. Default (or None): ``ErrorModel()``, 3%
+        relative.
+
+    Raises
+    ------
+    TypeError
+        If ``survey`` or ``error`` has the wrong type.
+    ValueError
+        If ``rhoa`` does not have one finite value per reading, or if no
+        reading is usable.
+
+    Warns
+    -----
+    DataWarning
+        If readings are removed.
+
+    Notes
+    -----
+    The data weights use the observed transfer resistances, while
+    :meth:`synthetic` draws noise with standard deviations computed from the
+    noise-free ones; with an absolute error part, readings that happen to come
+    out low are therefore weighted slightly less.
+
+    Examples
+    --------
+    >>> from ertkit.ves import Sounding, Survey
+    >>> survey = Survey.schlumberger(ab2=[3.0, 10.0, 30.0], mn2=0.5)
+    >>> Sounding(survey=survey, rhoa=[120.0, 80.0, 150.0]).n_data
+    3
+    """
+
+    survey: Survey
+    rhoa: NDArray[np.float64]
+    error: ErrorModel = field(default_factory=ErrorModel)
+
+    def __post_init__(self) -> None:
+        # Checked through plain objects: callers may pass anything at runtime.
+        survey_obj: object = self.survey
+        error_obj: object = self.error
+        if not isinstance(survey_obj, Survey):
+            raise TypeError(f"survey must be a Survey, got {type(survey_obj).__name__}")
+        if error_obj is None:
+            object.__setattr__(self, "error", ErrorModel())
+        elif not isinstance(error_obj, ErrorModel):
+            raise TypeError(
+                f"error must be an ErrorModel, got {type(error_obj).__name__}"
+            )
+        rhoa = np.array(self.rhoa, dtype=np.float64, copy=True, ndmin=1)
+        if rhoa.shape != (self.survey.n_readings,):
+            raise ValueError(
+                f"need {self.survey.n_readings} apparent resistivities, got shape {rhoa.shape}"
+            )
+        if not np.all(np.isfinite(rhoa)):
+            raise ValueError("apparent resistivities must be finite")
+        keep = self.error.usable(rhoa / self.survey.geometric_factor)
+        if not np.any(keep):
+            raise ValueError(
+                "no reading is usable (all R <= 0 or below the noise level)"
+            )
+        survey = self.survey
+        if not np.all(keep):
+            dropped = np.flatnonzero(~keep)
+            spacings = ", ".join(f"{v:.4g}" for v in self.survey.ab2[dropped])
+            warnings.warn(
+                f"removed {dropped.size} reading(s) with R <= 0 or |R| below three "
+                f"times the absolute error: indices {dropped.tolist()} "
+                f"(AB/2 = {spacings} m)",
+                DataWarning,
+                stacklevel=3,
+            )
+            survey = Survey(ab2=survey.ab2[keep], mn2=survey.mn2[keep])
+            rhoa = rhoa[keep]
+        rhoa.setflags(write=False)
+        object.__setattr__(self, "survey", survey)
+        object.__setattr__(self, "rhoa", rhoa)
+
+    @classmethod
+    def synthetic(
+        cls,
+        model: LayeredModel,
+        survey: Survey,
+        error: ErrorModel | None = None,
+        rng: int | np.random.Generator | None = None,
+    ) -> Sounding:
+        r"""Simulate noisy data from a layered model.
+
+        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.
+
+        Parameters
+        ----------
+        model : LayeredModel
+            The true model.
+        survey : Survey
+            Electrode half-spacings.
+        error : ErrorModel, optional
+            Error model used both to draw the noise and to weight the data.
+            Default ``ErrorModel()``.
+        rng : int, numpy.random.Generator or None, optional
+            Seed or generator, normalized with :func:`numpy.random.default_rng`.
+
+        Returns
+        -------
+        Sounding
+        """
+        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)
+
+    @property
+    def n_data(self) -> int:
+        """Number of readings."""
+        return int(self.rhoa.size)
+
+    @property
+    def resistance(self) -> NDArray[np.float64]:
+        r"""Transfer resistance :math:`R = \rho_a / K`, in ohms."""
+        return self.rhoa / self.survey.geometric_factor
+
+    @property
+    def log_data(self) -> NDArray[np.float64]:
+        r"""The inverted data :math:`d = \ln \rho_a`."""
+        return np.log(self.rhoa)
+
+    @property
+    def log_std(self) -> NDArray[np.float64]:
+        r"""Standard deviation of :math:`\ln \rho_a` for each reading."""
+        return self.error.log_std(self.resistance)

ertkit/ves/forward.py

@@ -0,0 +1,232 @@
+r"""Forward modeling of vertical electrical soundings over a layered earth.
+
+The potential on the surface at distance :math:`r` from a point source of
+current :math:`I` is
+
+.. math::
+
+    V(r) = \frac{I}{2\pi} \int_0^\infty \mathcal{T}_1(\lambda) J_0(\lambda r) \, d\lambda,
+
+where :math:`\mathcal{T}_1` is the resistivity transform of the layered earth
+(Pekeris 1940; Koefoed 1979). The integral is evaluated with the 120-point
+digital linear filter of Guptasarma and Singh (1997), taken from libdlf
+(https://github.com/emsig/libdlf; filter values licensed CC BY 4.0). Its
+relative error is below about 1e-6 for resistivity contrasts up to 1e4 between
+layers, and grows in proportion to the contrast beyond that.
+
+The functions here accept complex resistivities and thicknesses, so that
+derivatives can be computed by the complex-step method.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import cache
+from typing import Any
+
+import libdlf
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ertkit.ves.model import LayeredModel
+from ertkit.ves.survey import Survey
+
+__all__ = ["forward", "hankel_j0", "potential", "resistivity_transform"]
+
+
+@cache
+def _filter() -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Base and J0 weights of the Guptasarma and Singh (1997) 120-point filter."""
+    base, weights = libdlf.hankel.gupt_120_1997()
+    return np.asarray(base, dtype=np.float64), np.asarray(weights, dtype=np.float64)
+
+
+def _tanh(z: NDArray[Any]) -> NDArray[Any]:
+    """Hyperbolic tangent that is safe for complex arguments with Re(z) >= 0.
+
+    numpy's complex ``tanh`` overflows for large real parts on some platforms
+    (Windows). Since :math:`\\lambda h` always has a positive real part here,
+    :math:`\\tanh z = -\\operatorname{expm1}(-2z)/(2 + \\operatorname{expm1}(-2z))`,
+    which cannot overflow, is used for complex input.
+    """
+    if not np.iscomplexobj(z):
+        return np.tanh(z)
+    em = np.expm1(-2.0 * z)
+    return np.asarray(-em / (2.0 + em))
+
+
+def resistivity_transform(
+    lam: ArrayLike, resistivity: ArrayLike, thickness: ArrayLike
+) -> NDArray[Any]:
+    r"""Resistivity transform :math:`\mathcal{T}_1(\lambda)` of a layered earth.
+
+    Computed by the recurrence
+
+    .. math::
+
+        \mathcal{T}_N = \rho_N, \qquad
+        \mathcal{T}_i = \frac{\mathcal{T}_{i+1} + \rho_i \tanh(\lambda h_i)}
+                             {1 + \mathcal{T}_{i+1} \tanh(\lambda h_i)/\rho_i},
+        \qquad i = N-1, \dots, 1.
+
+    Parameters
+    ----------
+    lam : array_like
+        Hankel-transform variable :math:`\lambda`, in 1/m; any shape.
+    resistivity : array_like
+        Layer resistivities in ohm meters, length :math:`N`.
+    thickness : array_like
+        Thicknesses in meters of the upper :math:`N - 1` layers.
+
+    Returns
+    -------
+    ndarray
+        :math:`\mathcal{T}_1(\lambda)` in ohm meters, with the shape of ``lam``.
+        Complex if any input is complex.
+    """
+    rho = np.asarray(resistivity)
+    h = np.asarray(thickness)
+    lam = np.asarray(lam)
+    if rho.ndim != 1 or h.shape != (rho.size - 1,):
+        raise ValueError(
+            f"need {rho.size - 1} thicknesses for {rho.size} resistivities, "
+            f"got shape {h.shape}"
+        )
+    out = np.broadcast_to(rho[-1], lam.shape).astype(np.result_type(lam, rho, h, 1.0))
+    for i in range(rho.size - 2, -1, -1):
+        # A thickness with no imaginary part (all but the perturbed one, in a
+        # complex-step derivative) takes the much faster real tanh.
+        h_i = h[i].real if np.iscomplexobj(h) and h[i].imag == 0 else h[i]
+        t = _tanh(lam * h_i)
+        out = (out + rho[i] * t) / (1.0 + out * t / rho[i])
+    return out
+
+
+def hankel_j0(
+    kernel: Callable[[NDArray[np.float64]], NDArray[Any]], r: ArrayLike
+) -> NDArray[Any]:
+    r"""Zeroth-order Hankel transform by digital linear filtering.
+
+    Approximates
+
+    .. math::
+
+        F(r) = \int_0^\infty f(\lambda) J_0(\lambda r) \, d\lambda
+             \approx \frac{1}{r} \sum_j f(b_j / r) \, w_j,
+
+    with the base :math:`b_j` and weights :math:`w_j` of the 120-point filter
+    of Guptasarma and Singh (1997).
+
+    Parameters
+    ----------
+    kernel : callable
+        The function :math:`f`. It receives an array of :math:`\lambda` values
+        of shape ``(len(r), 120)`` and must return an array of the same shape.
+    r : array_like
+        Positive distances in meters, one-dimensional.
+
+    Returns
+    -------
+    ndarray
+        :math:`F(r)`, one value per distance.
+
+    Raises
+    ------
+    ValueError
+        If a distance is not positive and finite.
+
+    Notes
+    -----
+    Filter values from libdlf (https://github.com/emsig/libdlf), licensed
+    CC BY 4.0.
+    """
+    base, weights = _filter()
+    r = np.atleast_1d(np.asarray(r, dtype=np.float64))
+    if r.ndim != 1 or np.any(~(r > 0)) or not np.all(np.isfinite(r)):
+        raise ValueError("distances must be a one-dimensional array of positive values")
+    lam = base[np.newaxis, :] / r[:, np.newaxis]
+    values = np.asarray(kernel(lam))
+    # An explicit sum rather than a matrix product: some BLAS builds (Accelerate
+    # with numpy 2.0) raise spurious floating-point warnings in matmul.
+    return np.asarray((values * weights).sum(axis=-1) / r)
+
+
+def _rhoa(
+    resistivity: NDArray[Any],
+    thickness: NDArray[Any],
+    ab2: NDArray[np.float64],
+    mn2: NDArray[np.float64],
+) -> NDArray[Any]:
+    """Apparent resistivity of symmetric soundings; complex inputs allowed."""
+    near = ab2 - mn2
+    far = ab2 + mn2
+    r = np.concatenate([near, far])
+    v = hankel_j0(lambda lam: resistivity_transform(lam, resistivity, thickness), r) / (
+        2.0 * np.pi
+    )
+    v_near, v_far = v[: ab2.size], v[ab2.size :]
+    # Delta V = V(AM) - V(BM) - V(AN) + V(BN) = 2 [V(near) - V(far)] for I = 1 A.
+    k = 2.0 * np.pi / (2.0 / near - 2.0 / far)
+    return np.asarray(k * 2.0 * (v_near - v_far))
+
+
+def potential(
+    model: LayeredModel, r: ArrayLike, current: float = 1.0
+) -> NDArray[np.float64]:
+    """Surface potential at distance ``r`` from a point current source.
+
+    Parameters
+    ----------
+    model : LayeredModel
+        The layered earth.
+    r : array_like
+        Distances in meters from the source, positive.
+    current : float, optional
+        Source current in amperes. Default 1.
+
+    Returns
+    -------
+    ndarray of float
+        Potential in volts, one value per distance.
+
+    Raises
+    ------
+    ValueError
+        If a distance is not positive and finite.
+    """
+    r = np.atleast_1d(np.asarray(r, dtype=np.float64))
+    if np.any(~(r > 0)) or not np.all(np.isfinite(r)):
+        raise ValueError("distances must be positive and finite")
+    integral = hankel_j0(
+        lambda lam: resistivity_transform(lam, model.resistivity, model.thickness), r
+    )
+    return np.asarray(current * integral.real / (2.0 * np.pi), dtype=np.float64)
+
+
+def forward(model: LayeredModel, survey: Survey) -> NDArray[np.float64]:
+    """Apparent resistivities of a sounding over a layered earth.
+
+    Parameters
+    ----------
+    model : LayeredModel
+        The layered earth.
+    survey : Survey
+        The readings, with their half-spacings.
+
+    Returns
+    -------
+    ndarray of float
+        Apparent resistivity in ohm meters, one value per reading. The finite
+        potential-electrode spacing is modeled exactly.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ertkit.ves import LayeredModel, Survey, forward
+    >>> survey = Survey.schlumberger(ab2=[3.0, 30.0, 300.0], mn2=0.5)
+    >>> model = LayeredModel(resistivity=[100.0], thickness=[])
+    >>> np.allclose(forward(model, survey), 100.0)
+    True
+    """
+    rhoa = _rhoa(model.resistivity, model.thickness, survey.ab2, survey.mn2)
+    return np.asarray(rhoa.real, dtype=np.float64)