pycsamt 2.2.0__tar.gz → 2.2.2__tar.gz

{pycsamt-2.2.0/pycsamt.egg-info → pycsamt-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycsamt
-Version: 2.2.0
+Version: 2.2.2
 Summary: Scientific Python for electromagnetic geophysics — processing, inversion, AI agents, and apps
 Author-email: Laurent Kouadio <etanoyau@gmail.com>
 Maintainer-email: Laurent Kouadio <etanoyau@gmail.com>
@@ -36,6 +36,9 @@ Requires-Dist: tqdm>=4.60
 Requires-Dist: click>=8.1
 Requires-Dist: rich>=13.0
 Requires-Dist: typing_extensions>=4.1; python_version < "3.10"
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: empymod>=2.5
+Requires-Dist: h5py>=3.8
 Provides-Extra: torch
 Requires-Dist: torch>=1.13; extra == "torch"
 Provides-Extra: tensorflow
@@ -44,7 +47,6 @@ Provides-Extra: geo
 Requires-Dist: pyproj>=3.3; extra == "geo"
 Requires-Dist: xarray>=2022.6; extra == "geo"
 Requires-Dist: contextily>=1.6; extra == "geo"
-Requires-Dist: h5py>=3.8; extra == "geo"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.2; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -52,7 +54,6 @@ Requires-Dist: pytest-timeout>=2.3; extra == "dev"
 Requires-Dist: pytest-xdist>=3.5; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: pre-commit>=3.0; extra == "dev"
-Requires-Dist: scikit-learn>=1.1; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.2; extra == "docs"
 Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/__init__.py

@@ -17,7 +17,7 @@ try:
 
     __version__ = _pkg_version(__name__)
 except Exception:
-    __version__ = "2.2.0"
+    __version__ = "2.2.2"
 
 # ── Removed v1 names ──────────────────────────────────────────────────────────
 # Defined BEFORE logging (and before __getattr__) so this dict is always

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/_session.py

@@ -145,8 +145,8 @@ class Session(CoreObject):
 
     References
     ----------
-    .. [1] Python Stdlib. *context managers* (`with` statement).
-    .. [2] NumPy. *np.savez_compressed* used by registry packers.
+    .. [Session-1] Python Stdlib. *context managers* (`with` statement).
+    .. [Session-2] NumPy. *np.savez_compressed* used by registry packers.
     """
 
     def __init__(
@@ -473,8 +473,8 @@ class Normalize(CoreObject):
 
     References
     ----------
-    .. [1] D. Wight (1991). *SEG MT/EMAP EDI Standard*.
-    .. [2] Zonge International. *AVG data format*, tech notes.
+    .. [Normalize-1] D. Wight (1991). *SEG MT/EMAP EDI Standard*.
+    .. [Normalize-2] Zonge International. *AVG data format*, tech notes.
     """
 
     def __init__(

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/api/plot.py

@@ -107,19 +107,10 @@ Each token is a format extension (without the leading dot):
 Supported formats: ``png``, ``svg``, ``pdf``, ``eps``, ``tiff``,
 ``jpg``/``jpeg``.
 
-PlotConfig attributes
----------------------
-.. autosummary::
-
-   PlotConfig.fmt
-   PlotConfig.base_fmt
-   PlotConfig.dpi
-   PlotConfig.bbox_inches
-   PlotConfig.transparent
-   PlotConfig.facecolor
-   PlotConfig.savedir
-   PlotConfig.close_after_save
-   PlotConfig.verbose
+See :class:`PlotConfig` below for the full list of configurable
+attributes (``fmt``, ``base_fmt``, ``dpi``, ``bbox_inches``,
+``transparent``, ``facecolor``, ``savedir``, ``close_after_save``,
+``verbose``).
 """
 
 from __future__ import annotations

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/api/util.py

@@ -56,9 +56,9 @@ class TerminalSize:
 
     References
     ----------
-    .. [1] Python Software Foundation. Python Language Reference, version 3.9.
+    .. [TerminalSize-1] Python Software Foundation. Python Language Reference, version 3.9.
        Available at http://www.python.org
-    .. [2] Python `shutil` module documentation. Available at
+    .. [TerminalSize-2] Python `shutil` module documentation. Available at
        https://docs.python.org/3/library/shutil.html#get_terminal_size
     """
 
@@ -667,7 +667,7 @@ def get_table_width_from(
 
     References
     ----------
-    .. [1] McKinney, Wes. "Data Structures for Statistical Computing in Python."
+    .. [get-table-width-from-1] McKinney, Wes. "Data Structures for Statistical Computing in Python."
            Proceedings of the 9th Python in Science Conference. 2010.
     """
     border_lines = [
@@ -1452,9 +1452,9 @@ def count_functions(
 
     References
     ----------
-    .. [1] Python Software Foundation. Python Language Reference, version 3.9.
+    .. [count-functions-1] Python Software Foundation. Python Language Reference, version 3.9.
        Available at http://www.python.org
-    .. [2] Python `ast` module documentation. Available at
+    .. [count-functions-2] Python `ast` module documentation. Available at
        https://docs.python.org/3/library/ast.html
     """
 
@@ -1592,7 +1592,7 @@ def round_numeric_values(df, precision=4):
 
     References
     ----------
-    .. [1] "NumPy Documentation", https://numpy.org/doc/stable/
+    .. [round-numeric-values-1] "NumPy Documentation", https://numpy.org/doc/stable/
 
     """
 

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/api/view/frame.py

@@ -391,7 +391,23 @@ def maybe_wrap_frame(
     if api is False:
         return data
     if api is True:
-        # Explicit per-call override: always produce an APIFrame.
+        # Explicit per-call override: always wrap. A configured custom
+        # wrapper still applies here -- only an explicit "pandas"/disabled
+        # backend is overridden, since that would contradict "always wrap".
+        from .config import PYCSAMT_API_VIEW
+
+        if callable(PYCSAMT_API_VIEW.backend):
+            return wrap_frame(
+                data,
+                name=name,
+                kind=kind,
+                source=source,
+                units=units,
+                meta=meta,
+                description=description,
+                copy=copy,
+                **frame_kwargs,
+            )
         return _default_wrap_frame(
             data,
             name=name,

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/core/_registry.py

@@ -508,8 +508,8 @@ class FileManifestStore(ManifestStore):
 
     References
     ----------
-    .. [1] Python Standard Library. *json* module.
-    .. [2] Python 3.11+. *tomllib* — TOML parser.
+    .. [FileManifestStore-1] Python Standard Library. *json* module.
+    .. [FileManifestStore-2] Python 3.11+. *tomllib* — TOML parser.
     """
 
     def load(self, path: Path) -> Manifest:
@@ -654,9 +654,9 @@ class Registry(CoreObject):
 
     References
     ----------
-    .. [1] D. Wight (1991). *SEG MT/EMAP EDI Standard*.
+    .. [Registry-1] D. Wight (1991). *SEG MT/EMAP EDI Standard*.
        Society of Exploration Geophysicists.
-    .. [2] Python Standard Library. *pathlib* module.
+    .. [Registry-2] Python Standard Library. *pathlib* module.
     """
 
     def __init__(

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/core/registry.py

@@ -76,7 +76,7 @@ def register_packer(kind: str, packer: Packer) -> None:
 
     References
     ----------
-    .. [1] NumPy. ``np.savez_compressed`` for NPZ payloads.
+    .. [register-packer-1] NumPy. ``np.savez_compressed`` for NPZ payloads.
     """
 
     if not kind or not isinstance(kind, str):
@@ -275,7 +275,7 @@ def pack_to_file(
 
     References
     ----------
-    .. [1] NumPy Reference. *np.savez_compressed*.
+    .. [pack-to-file-1] NumPy Reference. *np.savez_compressed*.
     """
 
     p = Path(path)
@@ -423,8 +423,8 @@ class RegistryAPI(CoreObject):
 
     References
     ----------
-    .. [1] D. Wight (1991). *SEG MT/EMAP EDI Standard*.
-    .. [2] NumPy Reference. *np.savez_compressed*, *np.load*.
+    .. [RegistryAPI-1] D. Wight (1991). *SEG MT/EMAP EDI Standard*.
+    .. [RegistryAPI-2] NumPy Reference. *np.savez_compressed*, *np.load*.
     """
 
     def __init__(

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/emtools/plot.py

@@ -1429,7 +1429,7 @@ def plot_response_tipper(
             bbox_to_anchor=(0.38, -0.015),
             fontsize=8,
         )
-    if show_tipper_legend:
+    if show_tipper_legend and tips:
         real_style = PYCSAMT_STYLE.mt.xy
         imag_style = PYCSAMT_STYLE.mt.yx.copy(
             ls="--",

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/forward/em1d.py

@@ -12,11 +12,9 @@ Three EM methods are provided, all using the same
     MT/AMT/CSAMT far-field training data.
 
 ``TEM1DForward``
-    Central-loop time-domain EM (step-off waveform).  Computes the
-    frequency-domain H_z via a Hankel transform of the TE admittance
-    kernel, then converts to time via a cosine transform.  Uses
-    ``scipy.integrate`` (correct but not optimised; a DLF
-    acceleration layer is planned for Phase 2).
+    Central-loop time-domain EM (step-off waveform).  Delegates the
+    Hankel/Fourier transform to :mod:`empymod`'s validated digital
+    linear filters rather than a hand-rolled quadrature.
 
 ``CSAMT1DForward``
     Controlled-source AMT.  In the far-field limit this reduces to
@@ -192,82 +190,9 @@ def _z_surface_mt(omega: float, rho: np.ndarray, thick: np.ndarray) -> complex:
     return Z
 
 
-def _te_admittance(
-    lam: np.ndarray, omega: float, rho: np.ndarray, thick: np.ndarray
-) -> np.ndarray:
-    """
-    Vectorised TE-mode surface admittance Y_TE(λ, ω) for all λ at once.
-
-    Parameters
-    ----------
-    lam : ndarray (n_lam,)
-        Horizontal wavenumbers [1/m].
-    omega : float
-        Angular frequency [rad/s].
-    rho, thick : as in _z_surface_mt
-
-    Returns
-    -------
-    Y_TE : ndarray (n_lam,), complex
-    """
-    sigma = 1.0 / rho  # conductivities
-
-    # Vertical wavenumber  ν_j² = λ² + iωμ₀σ_j
-    # Shape broadcast: (n_lam, n_layers)
-    nu = np.sqrt(lam[:, None] ** 2 + 1j * omega * MU0 * sigma[None, :])
-
-    # Intrinsic TE admittance Y0_j = ν_j / (iωμ₀)
-    Y0 = nu / (1j * omega * MU0)  # (n_lam, n_layers)
-
-    # Start from halfspace
-    Y = Y0[:, -1].copy()  # (n_lam,)
-
-    for j in range(len(rho) - 2, -1, -1):
-        Y0j = Y0[:, j]
-        nu_j = nu[:, j]
-        th = np.tanh(nu_j * thick[j])
-        Y = Y0j * (Y + Y0j * th) / (Y0j + Y * th)
-
-    return Y
-
-
-def _hankel_hz_fd(
-    omega: float,
-    rho: np.ndarray,
-    thick: np.ndarray,
-    loop_radius: float,
-    n_lam: int = 150,
-) -> complex:
-    """
-    Frequency-domain H_z at the centre of a horizontal circular loop of
-    radius *loop_radius* over a 1-D earth.
-
-    The integral ∫₀^∞ λ · r_TE(λ,ω) · J₁(λa) dλ is evaluated with
-    Gauss-Legendre quadrature in log(λ) space.
-
-    Returns H_z per unit moment [1/m³].
-    """
-    from numpy.polynomial.legendre import leggauss
-    from scipy.special import j1 as J1
-
-    a = loop_radius
-    lam_lo = np.log(1e-5 / a)
-    lam_hi = np.log(1e5 / a)
-
-    nodes, wts = leggauss(n_lam)
-    t = 0.5 * (lam_hi - lam_lo) * nodes + 0.5 * (lam_hi + lam_lo)
-    lam = np.exp(t)
-    jac = 0.5 * (lam_hi - lam_lo)
-
-    Y_TE = _te_admittance(lam, omega, rho, thick)
-    Y0_air = lam / (1j * omega * MU0)  # air admittance ν₀/iωμ₀ ≈ λ/iωμ₀
-
-    r_TE = (Y0_air - Y_TE) / (Y0_air + Y_TE)
-
-    # Kernel:  λ · r_TE · J₁(λa)  ×  λ (Jacobian for log substitution)
-    integrand = lam * r_TE * J1(lam * a) * lam
-
-    return jac * complex(np.dot(wts, integrand)) / (4.0 * np.pi)
+# TEM1DForward's frequency-domain Hankel transform and time-domain Fourier
+# transform are delegated to empymod (Werthmüller, 2017) rather than
+# hand-rolled here -- see TEM1DForward's docstring for why.
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -358,15 +283,28 @@ class TEM1DForward(_Base1DForward):
     """
     1-D central-loop TEM forward solver (step-off waveform).
 
-    Computes the vertical magnetic field H_z(ω) via a numerical Hankel
-    transform of the TE admittance kernel, then converts to the step-off
-    time-domain dBz/dt via a cosine transform.
+    Computes the vertical magnetic field via :mod:`empymod`'s validated
+    digital-linear-filter Hankel and Fourier transforms
+    (Werthmüller, 2017), rather than a hand-rolled quadrature.
 
     .. note::
-        This implementation uses ``scipy.integrate`` for correctness.
-        It is suitable for generating training datasets of moderate size
-        (up to ~10 000 samples).  A Digital Linear Filter (DLF)
-        optimisation yielding 100× speed-up is planned for Phase 2.
+        An earlier from-scratch implementation (fixed-order Gauss-Legendre
+        Hankel transform + naive trapezoidal cosine transform) did not
+        converge at realistic time ranges -- its own frequency-domain
+        kernel grew unboundedly at high frequency instead of decaying, and
+        refining either quadrature's resolution changed the answer's
+        *sign*, not just its accuracy, at several requested times. That
+        implementation is gone; :mod:`empymod` is a peer-reviewed,
+        independently validated EM modelling library built specifically
+        for this class of problem, and is verified byte-for-byte against
+        Ward & Hohmann (1988)'s own closed-form half-space dBz/dt formula
+        (their eq. 4.70) as part of this module's test suite.
+
+    The loop itself is represented as a small tangential electric bipole
+    at the loop radius, scaled by the loop's circumference -- the same
+    "loop as a scaled dipole segment" construction :mod:`empymod` uses to
+    reproduce Ward & Hohmann's own central-loop figures (4.7-4.8), valid
+    by the axisymmetry of a horizontal circular loop.
 
     Parameters
     ----------
@@ -377,14 +315,20 @@ class TEM1DForward(_Base1DForward):
         Transmitter loop radius [m].  Default 50 m.
     moment : float
         Transmitter magnetic moment [A·m²].  Default 1 A·m².
-    n_freqs : int
-        Number of frequency-domain evaluation points used in the
-        cosine transform.  Higher → better accuracy at early times.
+    n_freqs, n_lam : int
+        Unused. Accepted only so existing callers (e.g.
+        :class:`pycsamt.inversion.backends.builtin.Builtin1DBackend`,
+        which threads ``backend_options`` straight through) do not break;
+        :mod:`empymod`'s own filters pick their resolution automatically.
 
     References
     ----------
     Ward & Hohmann (1988), *Electromagnetic Methods in Applied
     Geophysics*, Vol. 1.
+
+    Werthmüller, D. (2017). An open-source full 3D electromagnetic
+    modeler for 1D VTI media in Python: empymod. *Geophysics*, 82(6),
+    WB9-WB19.
     """
 
     def __init__(
@@ -400,16 +344,40 @@ class TEM1DForward(_Base1DForward):
         self.moment = float(moment)
         self.n_freqs = n_freqs
         self.n_lam = n_lam
-        # Pre-compute frequency grid for the cosine transform
+        # Frequency grid for the (informational) hz_freq field only --
+        # not used by the dBz/dt computation itself.
         t_min = self.times.min()
         t_max = self.times.max()
-        # Cover 4 decades below/above the time window
         self._omega = np.logspace(
             np.log10(2.0 * np.pi / (10.0 * t_max)),
             np.log10(2.0 * np.pi / (t_min / 10.0)),
             n_freqs,
         )
 
+    def _empymod_kwargs(self, model) -> dict:
+        rho = np.asarray(model.resistivity, dtype=float)
+        thick = np.asarray(model.thickness, dtype=float)
+        a = self.loop_radius
+
+        res = np.concatenate(([2e14], rho))  # air, then earth layers
+        depth = np.concatenate(([0.0], np.cumsum(thick)))
+
+        # A loop driven by current I has magnetic moment m = I * area;
+        # empymod's loop-as-bipole trick wants strength = I * circumference
+        # = (m / area) * (2*pi*a) = 2*m/a.
+        strength = 2.0 * self.moment / a
+
+        return dict(
+            src=[a, 0.0, 0.0, 90.0, 0.0],
+            rec=[0.0, 0.0, 0.0, 0.0, 90.0],
+            depth=depth.tolist(),
+            res=res.tolist(),
+            strength=strength,
+            mrec=True,
+            epermH=[0.0] * res.size,  # reduces early-time numerical noise
+            verb=0,
+        )
+
     def run(self, model) -> ForwardResponse:
         """
         Compute the TEM 1-D step-off response for *model*.
@@ -424,24 +392,25 @@ class TEM1DForward(_Base1DForward):
         ForwardResponse
             Fields populated: ``dBz_dt``, ``hz_freq``, ``times``.
         """
-        rho = model.resistivity
-        thick = model.thickness
+        import empymod
 
-        # Frequency-domain H_z at each ω
-        hz_fd = (
-            np.array(
-                [
-                    _hankel_hz_fd(w, rho, thick, self.loop_radius, self.n_lam)
-                    for w in self._omega
-                ],
-                dtype=complex,
-            )
-            * self.moment
+        kwargs = self._empymod_kwargs(model)
+
+        # signal=0 (impulse response) is dBz/dt for a step-off source --
+        # standard LTI result: d/dt of the switch-off step equals minus
+        # the impulse response, and empymod returns that derivative
+        # directly (verified against Ward & Hohmann 1988 eq. 4.70).
+        dBz_dt = np.asarray(
+            empymod.bipole(freqtime=self.times, signal=0, **kwargs).real,
+            dtype=float,
         )
 
-        # Time-domain dBz/dt via cosine transform
-        # dBz/dt(t) ≈ (2/π) × ∫₀^∞ ω · Im[H_z(ω)] · cos(ωt) dω
-        dBz_dt = self._cosine_transform(hz_fd)
+        hz_fd = np.asarray(
+            empymod.bipole(
+                freqtime=self._omega / (2.0 * np.pi), signal=None, **kwargs
+            ),
+            dtype=complex,
+        )
 
         return ForwardResponse(
             method="TEM1D",
@@ -451,22 +420,6 @@ class TEM1DForward(_Base1DForward):
             model=model,
         )
 
-    def _cosine_transform(self, hz_fd: np.ndarray) -> np.ndarray:
-        """Numerical cosine transform → dBz/dt at self.times."""
-        omega = self._omega
-        dlog_omega = np.diff(np.log(omega))  # spacings
-        # Trapezoidal integration in log(ω) space
-        # ∫ f(ω) dω  ≈  Σ  f(ω_k) · ω_k · Δlog(ω)
-        result = np.empty(len(self.times))
-        for i, t in enumerate(self.times):
-            integrand = omega * np.imag(hz_fd) * np.cos(omega * t)
-            # Trapezoidal in log-space: integrate f(ω)*ω d(log ω)
-            pts = integrand * omega  # f·ω for log spacing
-            result[i] = (2.0 / np.pi) * np.sum(
-                0.5 * (pts[:-1] + pts[1:]) * dlog_omega
-            )
-        return result
-
 
 # ─────────────────────────────────────────────────────────────────────────────
 # CSAMT 1-D forward

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/inversion/doc.py

@@ -105,9 +105,9 @@ Run from a dictionary in one line::
     references="""
 References
 ----------
-.. [1] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
+.. [workflow-1] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
        Estimation and Inverse Problems*, 3rd edition. Elsevier.
-.. [2] Chave, A. D. and Jones, A. G. (2012). *The Magnetotelluric Method:
+.. [workflow-2] Chave, A. D. and Jones, A. G. (2012). *The Magnetotelluric Method:
        Theory and Practice*. Cambridge University Press.
 """,
 )
@@ -182,10 +182,10 @@ Coerce a mapping supplied in a configuration file::
     references="""
 References
 ----------
-.. [1] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
+.. [model-1] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
        inversion: A practical algorithm for generating smooth models from
        electromagnetic sounding data. *Geophysics*, 52(3), 289-300.
-.. [2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
+.. [model-2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
        Estimation and Inverse Problems*, 3rd edition. Elsevier.
 """,
 )
@@ -228,11 +228,11 @@ Use component masks to down-weight stations or samples::
     error_model_references="""
 References
 ----------
-.. [1] Tarantola, A. (2005). *Inverse Problem Theory and Methods for Model
+.. [errors-1] Tarantola, A. (2005). *Inverse Problem Theory and Methods for Model
        Parameter Estimation*. SIAM.
-.. [2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
+.. [errors-2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
        Estimation and Inverse Problems*, 3rd edition. Elsevier.
-.. [3] Chave, A. D. and Jones, A. G. (2012). *The Magnetotelluric Method:
+.. [errors-3] Chave, A. D. and Jones, A. G. (2012). *The Magnetotelluric Method:
        Theory and Practice*. Cambridge University Press.
 """,
 )
@@ -317,12 +317,12 @@ Read shared settings from an inversion config::
     references="""
 References
 ----------
-.. [1] Tikhonov, A. N. and Arsenin, V. Y. (1977). *Solutions of Ill-Posed
+.. [regularization-1] Tikhonov, A. N. and Arsenin, V. Y. (1977). *Solutions of Ill-Posed
        Problems*. Winston.
-.. [2] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
+.. [regularization-2] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
        inversion: A practical algorithm for generating smooth models from
        electromagnetic sounding data. *Geophysics*, 52(3), 289-300.
-.. [3] Farquharson, C. G. and Oldenburg, D. W. (1998). Non-linear inversion
+.. [regularization-3] Farquharson, C. G. and Oldenburg, D. W. (1998). Non-linear inversion
        using general measures of data misfit and model structure. *Geophysical
        Journal International*, 134(1), 213-227.
 """,
@@ -396,10 +396,23 @@ Summarize a result in logs or notebooks::
     references="""
 References
 ----------
-.. [1] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
+.. [result-1] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
        inversion: A practical algorithm for generating smooth models from
        electromagnetic sounding data. *Geophysics*, 52(3), 289-300.
-.. [2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
+.. [result-2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
+       Estimation and Inverse Problems*, 3rd edition. Elsevier.
+""",
+    # Same citations as `references`, but with distinct footnote labels:
+    # both blocks are interpolated into different classes' docstrings that
+    # render on the same page (pycsamt.inversion.results), so the labels
+    # must not collide.
+    references_uncertainty="""
+References
+----------
+.. [result-unc-1] Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam's
+       inversion: A practical algorithm for generating smooth models from
+       electromagnetic sounding data. *Geophysics*, 52(3), 289-300.
+.. [result-unc-2] Aster, R. C., Borchers, B. and Thurber, C. H. (2018). *Parameter
        Estimation and Inverse Problems*, 3rd edition. Elsevier.
 """,
 )
@@ -531,11 +544,11 @@ Build TDEM data from time gates and decay values::
     references="""
 References
 ----------
-.. [1] Simpson, F. and Bahr, K. (2005). *Practical Magnetotellurics*.
+.. [data-1] Simpson, F. and Bahr, K. (2005). *Practical Magnetotellurics*.
        Cambridge University Press.
-.. [2] Chave, A. D. and Jones, A. G. (2012). *The Magnetotelluric Method:
+.. [data-2] Chave, A. D. and Jones, A. G. (2012). *The Magnetotelluric Method:
        Theory and Practice*. Cambridge University Press.
-.. [3] Nabighian, M. N. and Macnae, J. C. (1991). Time domain electromagnetic
+.. [data-3] Nabighian, M. N. and Macnae, J. C. (1991). Time domain electromagnetic
        prospecting methods. In *Electromagnetic Methods in Applied Geophysics*,
        volume 2, SEG.
 """,

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/inversion/export.py

@@ -61,7 +61,7 @@ def to_csv(
 
     References
     ----------
-    .. [1] Shafranovich, Y. (2005). Common Format and MIME Type for
+    .. [to-csv-1] Shafranovich, Y. (2005). Common Format and MIME Type for
        Comma-Separated Values (CSV) Files. RFC 4180.
     """
     model = result.to_resistivity_model()
@@ -116,7 +116,7 @@ def to_npz(result: InversionResult, path: PathLike) -> Path:
 
     References
     ----------
-    .. [1] NumPy Developers. ``numpy.savez_compressed`` documentation.
+    .. [to-npz-1] NumPy Developers. ``numpy.savez_compressed`` documentation.
     """
     model = result.to_resistivity_model()
     out = Path(path)
@@ -187,7 +187,7 @@ def to_geojson(
 
     References
     ----------
-    .. [1] Butler, H. et al. (2016). The GeoJSON Format. RFC 7946.
+    .. [to-geojson-1] Butler, H. et al. (2016). The GeoJSON Format. RFC 7946.
     """
     model = result.to_resistivity_model()
     rho = np.asarray(model.rho_2d, dtype=float)
@@ -281,7 +281,7 @@ def to_vtk(
 
     References
     ----------
-    .. [1] Schroeder, W., Martin, K. and Lorensen, B. (2006). *The
+    .. [to-vtk-1] Schroeder, W., Martin, K. and Lorensen, B. (2006). *The
        Visualization Toolkit*, 4th edition.
     """
     model = result.to_resistivity_model()
@@ -352,8 +352,8 @@ def to_geotiff(
 
     References
     ----------
-    .. [1] Ritter, N. and Ruth, M. (1997). GeoTIFF Format Specification.
-    .. [2] Gillies, S. et al. Rasterio documentation.
+    .. [to-geotiff-1] Ritter, N. and Ruth, M. (1997). GeoTIFF Format Specification.
+    .. [to-geotiff-2] Gillies, S. et al. Rasterio documentation.
     """
     try:
         import rasterio
@@ -440,7 +440,7 @@ def to_archive(
 
     References
     ----------
-    .. [1] PKWARE Inc. ZIP File Format Specification.
+    .. [to-archive-1] PKWARE Inc. ZIP File Format Specification.
     """
     out = Path(path)
     out.parent.mkdir(parents=True, exist_ok=True)

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/inversion/mesh.py

@@ -57,7 +57,7 @@ class InversionMesh(PyCSAMTObject, MetadataMixin):
 
     References
     ----------
-    .. [1] Oldenburg, D. W. and Li, Y. (2005). Inversion for applied
+    .. [InversionMesh-1] Oldenburg, D. W. and Li, Y. (2005). Inversion for applied
        geophysics: A tutorial. In *Near-Surface Geophysics*, SEG.
     """
 
@@ -146,7 +146,7 @@ def depth_widths(
 
     References
     ----------
-    .. [1] Ward, S. H. and Hohmann, G. W. (1988). Electromagnetic theory for
+    .. [depth-widths-1] Ward, S. H. and Hohmann, G. W. (1988). Electromagnetic theory for
        geophysical applications. In *Electromagnetic Methods in Applied
        Geophysics*, volume 1, SEG.
     """

{pycsamt-2.2.0 → pycsamt-2.2.2}/pycsamt/inversion/objective.py

@@ -370,7 +370,7 @@ def weighted_rms(observed, predicted, errors=None) -> float:
 
     References
     ----------
-    .. [1] Tarantola, A. (2005). *Inverse Problem Theory and Methods for Model
+    .. [weighted-rms-1] Tarantola, A. (2005). *Inverse Problem Theory and Methods for Model
        Parameter Estimation*. SIAM.
     """
     obs = np.asarray(observed, dtype=float)