microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/__init__.py

@@ -0,0 +1,18 @@
+# odas-tpw: Ocean microstructure turbulence processing (ODAS heritage)
+#
+# Subpackages:
+#   rsi         — Rockland Scientific instrument I/O (.p files, NetCDF, profiles)
+#   chi         — Chi (thermal variance dissipation) calculation
+#   scor160     — ATOMIX shear-probe benchmark processing (L1-L4)
+#   processing  — Instrument-agnostic algorithms (top_trim, bottom, ct_align, etc.)
+#   perturb     — Full processing pipeline (trim, merge, calibrate, compute, bin)
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("microstructure-tpw")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

odas_tpw/chi/__init__.py

@@ -0,0 +1,48 @@
+# Chi (thermal variance dissipation) calculations
+#
+# Computes chi from temperature microstructure spectra using
+# Batchelor/Kraichnan spectral fitting (Method 2) or from known
+# epsilon via Dillon & Caldwell (Method 1).
+
+from odas_tpw.chi.batchelor import (
+    KAPPA_T,
+    Q_BATCHELOR,
+    Q_KRAICHNAN,
+    batchelor_grad,
+    batchelor_kB,
+    kraichnan_grad,
+)
+from odas_tpw.chi.fp07 import (
+    default_tau_model,
+    fp07_double_pole,
+    fp07_tau,
+    fp07_tau_batch,
+    fp07_transfer,
+    fp07_transfer_batch,
+)
+from odas_tpw.chi.l2_chi import L2ChiData, L2ChiParams, process_l2_chi
+from odas_tpw.chi.l3_chi import L3ChiData, process_l3_chi
+from odas_tpw.chi.l4_chi import L4ChiData, process_l4_chi_epsilon, process_l4_chi_fit
+
+__all__ = [
+    "KAPPA_T",
+    "Q_BATCHELOR",
+    "Q_KRAICHNAN",
+    "L2ChiData",
+    "L2ChiParams",
+    "L3ChiData",
+    "L4ChiData",
+    "batchelor_grad",
+    "batchelor_kB",
+    "default_tau_model",
+    "fp07_double_pole",
+    "fp07_tau",
+    "fp07_tau_batch",
+    "fp07_transfer",
+    "fp07_transfer_batch",
+    "kraichnan_grad",
+    "process_l2_chi",
+    "process_l3_chi",
+    "process_l4_chi_epsilon",
+    "process_l4_chi_fit",
+]

odas_tpw/chi/batchelor.py

@@ -0,0 +1,189 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Batchelor and Kraichnan temperature gradient spectra.
+
+References
+----------
+Dillon, T.M. and D.R. Caldwell, 1980: The Batchelor spectrum and dissipation
+    in the upper ocean. J. Geophys. Res., 85, 1910-1916.
+Bogucki, D., J.A. Domaradzki, and P.K. Yeung, 1997: Direct numerical
+    simulations of passive scalars with Pr > 1 advected by turbulent flow.
+    J. Fluid Mech., 343, 111-130.
+Oakey, N.S., 1982: Determination of the rate of dissipation of turbulent
+    energy. J. Phys. Oceanogr., 12, 256-271.
+"""
+
+import numpy as np
+import numpy.typing as npt
+from scipy.special import erfc
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Thermal diffusivity of seawater [m^2/s] at a ~15 degC reference — the BACKWARD-
+# COMPATIBLE FALLBACK only. The production chi pipeline now threads a per-window,
+# temperature-dependent kappa_T(T,S,P) (Sharqawy-2010 conductivity + gsw rho/cp,
+# see scor160/ocean.py:kappa_T) from the L3 stage through chi.py/l4_chi.py. That
+# T-dependence spans ~1.39e-7 at -1 degC to ~1.51e-7 at 32 degC; since
+# chi = 6*kappa_T*I and epsilon_T = (2*pi*kB)^4*nu*kappa_T^2, using it removed a
+# chi bias that ran from ~-1% (cold) to ~+8% (warm) against this fixed value.
+# This constant remains the default for the chi.py functions' `kappa_T=` argument
+# so a caller that does not supply a per-window value still runs.
+# See docs/chi_mathematics.md Section 11.
+KAPPA_T = 1.4e-7
+Q_BATCHELOR = 3.7  # Batchelor universal constant (Oakey 1982)
+Q_KRAICHNAN = 5.26  # Kraichnan universal constant (Bogucki et al. 1997)
+_SQ6Q_KRAICHNAN = np.sqrt(6 * Q_KRAICHNAN)  # Precomputed for kraichnan_grad
+
+
+# ---------------------------------------------------------------------------
+# Batchelor wavenumber
+# ---------------------------------------------------------------------------
+
+
+def batchelor_kB(
+    epsilon: float | np.ndarray, nu: float, kappa_T: float = KAPPA_T
+) -> float | np.ndarray:
+    """Batchelor wavenumber [cpm].
+
+    kB = (1/(2*pi)) * (epsilon / (nu * kappa_T^2))^(1/4)
+
+    Parameters
+    ----------
+    epsilon : float or array
+        TKE dissipation rate [W/kg].
+    nu : float
+        Kinematic viscosity [m^2/s].
+    kappa_T : float
+        Thermal diffusivity [m^2/s].
+
+    Returns
+    -------
+    kB : float or array
+        Batchelor wavenumber [cpm].
+    """
+    return (1 / (2 * np.pi)) * (epsilon / (nu * kappa_T**2)) ** 0.25
+
+
+# ---------------------------------------------------------------------------
+# Batchelor spectrum (Dillon & Caldwell 1980)
+# ---------------------------------------------------------------------------
+
+
+def batchelor_nondim(alpha: npt.ArrayLike) -> np.ndarray:
+    """Non-dimensional Batchelor gradient spectrum f_B(alpha).
+
+    f(alpha) = alpha * [exp(-alpha^2/2) - alpha * sqrt(pi/2) * erfc(alpha/sqrt(2))]
+
+    Dillon & Caldwell 1980, eq. 3.  Integral over [0, inf) = 1/3.
+
+    Parameters
+    ----------
+    alpha : array_like
+        Non-dimensional wavenumber: alpha = sqrt(2*q) * k / kB.
+
+    Returns
+    -------
+    f : ndarray
+    """
+    alpha = np.asarray(alpha, dtype=np.float64)
+    return alpha * (np.exp(-(alpha**2) / 2) - alpha * np.sqrt(np.pi / 2) * erfc(alpha / np.sqrt(2)))
+
+
+def batchelor_grad(
+    k: npt.ArrayLike,
+    kB: float | np.ndarray,
+    chi: float,
+    kappa_T: float = KAPPA_T,
+    q: float = Q_BATCHELOR,
+) -> np.ndarray:
+    """Batchelor temperature gradient spectrum [(K/m)^2 / cpm].
+
+    S(k) = sqrt(q/2) * chi / (kB * kappa_T) * f(alpha)
+    where alpha = sqrt(2*q) * k / kB
+
+    Dillon & Caldwell 1980, eq. 1.  k and kB in cpm.
+    Integrates to chi / (6 * kappa_T).
+
+    Parameters
+    ----------
+    k : array_like
+        Wavenumber [cpm].
+    kB : float
+        Batchelor wavenumber [cpm].
+    chi : float
+        Thermal variance dissipation rate [K^2/s].
+    kappa_T : float
+        Thermal diffusivity [m^2/s].
+    q : float
+        Universal constant.
+
+    Returns
+    -------
+    S : ndarray
+        Gradient spectrum [(K/m)^2 / cpm].
+    """
+    k = np.asarray(k, dtype=np.float64)
+    # Mirror kraichnan_grad: a degenerate kB (0 / NaN) otherwise yields
+    # NaN-with-warnings; sanitize to 0 so the spectrum stays finite (#16).
+    with np.errstate(divide="ignore", invalid="ignore"):
+        alpha = np.sqrt(2 * q) * k / kB
+        f = batchelor_nondim(alpha)
+        S = np.sqrt(q / 2) * chi / (kB * kappa_T) * f
+    return np.where(np.isfinite(S), S, 0.0)
+
+
+# ---------------------------------------------------------------------------
+# Kraichnan spectrum (Bogucki et al. 1997)
+# ---------------------------------------------------------------------------
+
+
+def kraichnan_grad(
+    k: npt.ArrayLike,
+    kB: float | np.ndarray,
+    chi: float,
+    kappa_T: float = KAPPA_T,
+    q: float = Q_KRAICHNAN,
+) -> np.ndarray:
+    """Kraichnan temperature gradient spectrum [(K/m)^2 / cpm].
+
+    S(k) = chi*q / (kappa_T*kB^2) * k * exp(-sqrt(6q)*y)
+    where y = k / kB.
+
+    This is the one-dimensional (along-path) gradient spectrum obtained by
+    applying the isotropic transform G1(k1) = k1^2 * int_{k1}^inf E(k)/k dk
+    to the three-dimensional Kraichnan scalar spectrum of Bogucki et al.
+    1997, eq. 11.  The transform evaluates in closed form to the simple
+    exponential above (the same form as Peterson & Fer 2014, eq. 8).
+    Integrates to chi / (6 * kappa_T); peaks at k = kB / sqrt(6q).
+
+    Key difference from Batchelor: exponential rolloff instead of Gaussian,
+    which fits DNS and observed high-Prandtl-number spectra better
+    (Bogucki et al. 1997).
+
+    Parameters
+    ----------
+    k : array_like
+        Wavenumber [cpm].
+    kB : float
+        Batchelor wavenumber [cpm].
+    chi : float
+        Thermal variance dissipation rate [K^2/s].
+    kappa_T : float
+        Thermal diffusivity [m^2/s].
+    q : float
+        Universal constant (default: 5.26).
+
+    Returns
+    -------
+    S : ndarray
+        Gradient spectrum [(K/m)^2 / cpm].
+    """
+    k = np.asarray(k, dtype=np.float64)
+    y = k / kB
+    sq6q = _SQ6Q_KRAICHNAN if q == Q_KRAICHNAN else np.sqrt(6 * q)
+    sq6q_y = sq6q * y
+    with np.errstate(divide="ignore", invalid="ignore"):
+        S = chi * q / (kappa_T * kB**2) * k * np.exp(-sq6q_y)
+    S = np.where(np.isfinite(S), S, 0.0)
+    return S