microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/scor160/nasmyth.py

@@ -0,0 +1,208 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Nasmyth universal shear spectrum.
+
+Uses Lueck's improved fit from ODAS v4.5.1, documented in
+McMillan et al. (2016), J. Atmos. Oceanic Techno., 33, 817-837.
+"""
+
+import warnings
+
+import numpy as np
+import numpy.typing as npt
+
+# Lueck (2022), J. Atmos. Oceanic Technol., 39(9), 1259-1271,
+# https://doi.org/10.1175/JTECH-D-21-0051.1
+LUECK_A = 1.0774e9  # e/e_10 model constant
+X_95 = 0.1205  # non-dimensional wavenumber for 95% variance
+
+
+def nasmyth(epsilon: float, nu: float, k: npt.ArrayLike) -> np.ndarray:
+    """Nasmyth shear spectrum at given wavenumbers.
+
+    Parameters
+    ----------
+    epsilon : float
+        Dissipation rate [W/kg].
+    nu : float
+        Kinematic viscosity [m²/s].
+    k : array_like
+        Wavenumber(s) [cpm].
+
+    Returns
+    -------
+    phi : ndarray
+        Shear spectrum [s⁻² cpm⁻¹].
+    """
+    if nu <= 0:
+        raise ValueError(f"Kinematic viscosity must be positive, got nu={nu}")
+    k = np.asarray(k, dtype=np.float64)
+    if epsilon <= 0:
+        warnings.warn(
+            f"epsilon={epsilon:.2e} <= 0; Nasmyth spectrum will contain NaN",
+            stacklevel=2,
+        )
+        return np.full_like(k, np.nan)
+    ks = (epsilon / nu**3) ** 0.25  # Kolmogorov wavenumber
+    x = k / ks
+    G2 = _nasmyth_g2(x)
+    return epsilon ** (3 / 4) * nu ** (-1 / 4) * G2
+
+
+def nasmyth_nondim(x: npt.ArrayLike) -> np.ndarray:
+    """Non-dimensional Nasmyth spectrum G2(x) where x = k/ks.
+
+    Parameters
+    ----------
+    x : array_like
+        Non-dimensional wavenumber k/ks.
+
+    Returns
+    -------
+    G2 : ndarray
+        Non-dimensional spectrum.
+    """
+    return _nasmyth_g2(np.asarray(x, dtype=np.float64))
+
+
+def _nasmyth_g2(x: np.ndarray) -> np.ndarray:
+    """Lueck's improved fit to the Nasmyth spectrum.
+
+    G2 = 8.05 * x^(1/3) / (1 + (20.6*x)^3.715)
+    """
+    return 8.05 * x ** (1 / 3) / (1 + (20.6 * x) ** 3.715)
+
+
+# ---------------------------------------------------------------------------
+# Grid-based fast lookup for G2(x)
+# ---------------------------------------------------------------------------
+
+
+class NasmythGrid:
+    """Pre-tabulated Nasmyth G2(x) on a log-spaced grid for fast interpolation.
+
+    The non-dimensional Nasmyth spectrum G2(x) depends only on x = k/ks.
+    By tabulating log10(G2) vs log10(x) once, subsequent evaluations reduce
+    to ``np.interp`` in log-space -- avoiding repeated power operations.
+
+    Parameters
+    ----------
+    n : int, optional
+        Number of grid points (default 2000).
+    x_min : float, optional
+        Minimum x value (default 1e-6).
+    x_max : float, optional
+        Maximum x value (default 1.0).
+    """
+
+    def __init__(self, n: int = 2000, x_min: float = 1e-6, x_max: float = 1.0) -> None:
+        self._log10_x = np.linspace(np.log10(x_min), np.log10(x_max), n)
+        x_grid = 10.0**self._log10_x
+        g2_grid = _nasmyth_g2(x_grid)
+        self._log10_g2 = np.log10(g2_grid)
+        # Cache boundary values for extrapolation fallback
+        self._x_min = x_min
+        self._x_max = x_max
+
+    def interp_g2(self, x: np.ndarray) -> np.ndarray:
+        """Interpolate G2 for arbitrary x values.
+
+        For x inside [x_min, x_max], log-space interpolation is used.
+        For x outside that range, G2 is computed directly via ``_nasmyth_g2``.
+
+        Parameters
+        ----------
+        x : ndarray
+            Non-dimensional wavenumber(s) k/ks.
+
+        Returns
+        -------
+        G2 : ndarray
+            Non-dimensional spectrum values.
+        """
+        # Hot caller pattern (1-D float64 ndarray): skip ``np.asarray`` /
+        # ``np.atleast_1d`` / ``.item()``-on-scalar; and use ``np.where``
+        # to fold the two-mask split into one allocation.  Math identical.
+        if isinstance(x, np.ndarray) and x.ndim == 1 and x.dtype == np.float64:
+            in_range_mask = (x >= self._x_min) & (x <= self._x_max)
+            # Compute the in-range branch on the entire array (interp clips
+            # to the lookup table's edges for OOR x; the multiplication by
+            # 10**log10_g2 still produces a number).  Then overwrite OOR
+            # cells with the direct-formula result.  This avoids the cost
+            # of constructing a boolean-indexed sub-array for the in-range
+            # case (which dominates when nearly all values are in range).
+            # log10 runs on the whole array (incl. out-of-range x<=0, e.g. a k=0
+            # DC bin); those cells are overwritten below, so silence the
+            # divide-by-zero / invalid warnings they would otherwise emit.
+            with np.errstate(divide="ignore", invalid="ignore"):
+                log10_g2 = np.interp(np.log10(x), self._log10_x, self._log10_g2)
+            result = 10.0**log10_g2
+            if not in_range_mask.all():
+                result[~in_range_mask] = _nasmyth_g2(x[~in_range_mask])
+            return result
+
+        x = np.asarray(x, dtype=np.float64)
+        scalar = x.ndim == 0
+        x = np.atleast_1d(x)
+
+        result = np.empty_like(x)
+
+        in_range = (x >= self._x_min) & (x <= self._x_max)
+        out_range = ~in_range
+
+        if np.any(in_range):
+            log10_x_query = np.log10(x[in_range])
+            log10_g2 = np.interp(log10_x_query, self._log10_x, self._log10_g2)
+            result[in_range] = 10.0**log10_g2
+
+        if np.any(out_range):
+            result[out_range] = _nasmyth_g2(x[out_range])
+
+        return result.item() if scalar else result
+
+
+# Module-level singleton, lazily initialized on first call to nasmyth_grid().
+_grid: NasmythGrid | None = None
+
+
+def _get_grid() -> NasmythGrid:
+    """Return the module-level NasmythGrid, creating it on first access."""
+    global _grid
+    if _grid is None:
+        _grid = NasmythGrid()
+    return _grid
+
+
+def nasmyth_grid(epsilon: float, nu: float, k: npt.ArrayLike) -> np.ndarray:
+    """Nasmyth shear spectrum using pre-tabulated G2 interpolation.
+
+    Drop-in replacement for :func:`nasmyth` that avoids repeated power
+    operations by interpolating on a pre-computed log-spaced grid of the
+    non-dimensional spectrum G2(x).
+
+    Parameters
+    ----------
+    epsilon : float
+        Dissipation rate [W/kg].
+    nu : float
+        Kinematic viscosity [m²/s].
+    k : array_like
+        Wavenumber(s) [cpm].
+
+    Returns
+    -------
+    phi : ndarray
+        Shear spectrum [s⁻² cpm⁻¹].
+    """
+    if nu <= 0:
+        raise ValueError(f"Kinematic viscosity must be positive, got nu={nu}")
+    k = np.asarray(k, dtype=np.float64)
+    if epsilon <= 0:
+        warnings.warn(
+            f"epsilon={epsilon:.2e} <= 0; Nasmyth spectrum will contain NaN",
+            stacklevel=2,
+        )
+        return np.full_like(k, np.nan)
+    ks = (epsilon / nu**3) ** 0.25  # Kolmogorov wavenumber
+    x = k / ks
+    G2 = _get_grid().interp_g2(x)
+    return epsilon ** (3 / 4) * nu ** (-1 / 4) * G2

odas_tpw/scor160/ocean.py

@@ -0,0 +1,287 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Seawater properties for turbulence calculations."""
+
+import numpy as np
+import numpy.typing as npt
+
+
+def visc35(T: npt.ArrayLike) -> np.ndarray:
+    """Kinematic viscosity of seawater at S=35, P=0 [m²/s].
+
+    Parameters
+    ----------
+    T : float or array_like
+        Temperature in °C. Valid for 0-20 °C.
+
+    Returns
+    -------
+    nu : float or ndarray
+        Kinematic viscosity in m²/s.
+
+    Reference: ODAS visc35.m — 3rd-order polynomial fit,
+    error < 1% for 0 ≤ T ≤ 20 °C, 30 ≤ S ≤ 40 PSU, atmospheric pressure.
+    """
+    pol = np.array(
+        [
+            -1.131311019739306e-011,
+            1.199552027472192e-009,
+            -5.864346822839289e-008,
+            1.828297985908266e-006,
+        ]
+    )
+    # The cubic fit (valid 0-20 C) crosses zero near 64.5 C and goes negative
+    # beyond it. A single spurious-hot temperature sample would then yield a
+    # negative viscosity and make nasmyth raise on sqrt(negative), crashing the
+    # whole file. Floor at a small positive value (well below any realistic
+    # seawater viscosity, so 0-~60 C is unaffected).
+    return np.maximum(np.polyval(pol, T), 1.0e-7)
+
+
+def visc(
+    T: npt.ArrayLike,
+    S: npt.ArrayLike = 35,
+    P: npt.ArrayLike = 0,
+    lon: npt.ArrayLike = 0,
+    lat: npt.ArrayLike = 0,
+) -> np.ndarray:
+    """Kinematic viscosity of seawater [m²/s].
+
+    For S=35, P=0 falls back to the visc35 polynomial (matches ODAS).
+    Otherwise uses Sharqawy et al. (2010) for dynamic viscosity
+    and gsw (TEOS-10) for in-situ density.
+
+    Note: the two branches differ by up to ~1.4% at the S=35/P=0 seam (max at
+    0 °C; ~0.7% at 5-15 °C), so nu is mildly discontinuous there. This is
+    intentional — visc35 is the ODAS reference used by the ATOMIX shear
+    benchmark at exactly S=35/P=0, so the seam is not blended. The seam is
+    unreachable in normal processing (in-situ P>0 keeps a cast on the Sharqawy
+    branch), and a ~1.4% nu change propagates to <0.5% in epsilon (#20).
+
+    Parameters
+    ----------
+    T : float or array_like
+        In-situ temperature [°C].
+    S : float or array_like
+        Practical salinity [PSU]. Default: 35.
+    P : float or array_like
+        Pressure [dbar]. Default: 0.
+    lon, lat : float or array_like
+        Longitude [°E] / latitude [°N] for the TEOS-10 Absolute-Salinity
+        composition anomaly. Default: 0. The anomaly is tiny at typical
+        depths, so this rarely matters; pass the cast position for consistency.
+
+    Returns
+    -------
+    nu : float or ndarray
+        Kinematic viscosity [m²/s].
+    """
+    T = np.asarray(T, dtype=float)
+    S = np.asarray(S, dtype=float)
+    P = np.asarray(P, dtype=float)
+
+    if np.all(S == 35) and np.all(P == 0):
+        return visc35(T)
+
+    import gsw
+
+    # Dynamic viscosity of pure water [Pa·s] — Sharqawy et al. (2010) Eq. 22
+    mu_w = 4.2844e-5 + (0.157 * (T + 64.993) ** 2 - 91.296) ** (-1)
+
+    # Salinity correction — Sharqawy et al. (2010) Eq. 23
+    A = 1.541 + 1.998e-2 * T - 9.52e-5 * T**2
+    B = 7.974 - 7.561e-2 * T + 4.724e-4 * T**2
+    S_frac = S * 1e-3  # PSU to mass fraction
+    mu = mu_w * (1 + A * S_frac + B * S_frac**2)
+
+    # In-situ density from gsw (TEOS-10)
+    SA = gsw.SA_from_SP(S, P, lon, lat)
+    CT = gsw.CT_from_t(SA, T, P)
+    rho = gsw.rho(SA, CT, P)
+
+    # Floor to a small positive value, mirroring visc35: a spurious-cold window
+    # mean (T well below 0) drives the Sharqawy polynomial negative, and a
+    # negative viscosity crashes the Nasmyth fit downstream.
+    return np.maximum(mu / rho, 1.0e-7)
+
+
+def kappa_T(
+    T: npt.ArrayLike,
+    S: npt.ArrayLike = 35,
+    P: npt.ArrayLike = 0,
+    lon: npt.ArrayLike = 0,
+    lat: npt.ArrayLike = 0,
+) -> np.ndarray:
+    """Molecular thermal diffusivity of seawater [m²/s].
+
+    ``kappa_T = k / (rho * c_p)`` where the thermal conductivity ``k`` follows
+    the Jamieson & Tudhope (1970) correlation as compiled by Sharqawy et al.
+    (2010, Eq. 13) and the in-situ density ``rho`` and isobaric specific heat
+    ``c_p`` come from gsw (TEOS-10, ``gsw.rho`` / ``gsw.cp_t_exact``). This is
+    the same style of "published correlation over gsw" path :func:`visc` uses
+    off the S=35/P=0 seam; unlike :func:`visc` there is no ODAS-polynomial
+    fallback branch, so ``kappa_T`` always uses gsw (there is no ``kappa35``).
+
+    Over 0-32 °C at S=35, P=0 this rises from ~1.39e-7 to ~1.51e-7 m²/s — the
+    ~+8% swing the fixed ``chi.batchelor.KAPPA_T = 1.4e-7`` used to miss. Because
+    ``chi = 6*kappa_T*I`` and ``epsilon_T = (2*pi*kB)^4*nu*kappa_T^2``, using the
+    true value removes a chi bias that ran from ~-1% at -1 °C to ~+8% at 32 °C.
+
+    Parameters
+    ----------
+    T : float or array_like
+        In-situ temperature [°C].
+    S : float or array_like
+        Practical salinity [PSU]. Default: 35.
+    P : float or array_like
+        Pressure [dbar]. Default: 0.
+    lon, lat : float or array_like
+        Longitude [°E] / latitude [°N] for the TEOS-10 Absolute-Salinity
+        composition anomaly. Default: 0. Immaterial at typical depths; pass the
+        cast position for consistency.
+
+    Returns
+    -------
+    kappa_T : float or ndarray
+        Thermal diffusivity [m²/s].
+
+    Reference: Sharqawy, Lienhard & Zubair (2010), "Thermophysical properties
+    of seawater", Desalination and Water Treatment 16, 354-380 — Eq. 13
+    (Jamieson & Tudhope 1970 thermal conductivity, ±3%, 0-180 °C, 0-160 g/kg).
+    """
+    import gsw
+
+    T = np.asarray(T, dtype=float)
+    S = np.asarray(S, dtype=float)
+    P = np.asarray(P, dtype=float)
+
+    # Clip a spurious window-mean temperature into the physical seawater range
+    # before evaluating ANY term (both the k correlation and the gsw density /
+    # specific heat). A wild T from a bad window sends the k polynomial outside
+    # its fitted domain AND drives gsw.cp_t_exact / gsw.rho into extrapolation
+    # where they can go negative — yielding a negative kappa_T (hence negative
+    # chi). -2 °C is below the freezing point at any ocean salinity; 40 °C is
+    # above the warmest sea surface. Must clip T for gsw too, not just for k.
+    T_c = np.clip(T, -2.0, 40.0)
+
+    # Thermal conductivity [mW/(m·K)] — Jamieson & Tudhope (1970), Sharqawy Eq. 13
+    # (T in °C, S in g/kg ≈ PSU for open-ocean salinities).
+    Tk = T_c + 273.15
+    log10_k = (
+        np.log10(240.0 + 0.0002 * S)
+        + 0.434
+        * (2.3 - (343.5 + 0.037 * S) / Tk)
+        * (1.0 - Tk / (647.3 + 0.03 * S)) ** (1.0 / 3.0)
+    )
+    k = 10.0**log10_k * 1.0e-3  # mW/(m·K) → W/(m·K)
+
+    # Density and isobaric specific heat from gsw (TEOS-10).
+    SA = gsw.SA_from_SP(S, P, lon, lat)
+    CT = gsw.CT_from_t(SA, T_c, P)
+    rho = gsw.rho(SA, CT, P)
+    cp = gsw.cp_t_exact(SA, T_c, P)
+
+    # Floor to a small positive value (mirrors visc/visc35): guards any residual
+    # non-physical combination (e.g. a wildly out-of-range salinity) from
+    # emitting a zero/negative diffusivity that would corrupt chi downstream.
+    return np.maximum(k / (rho * cp), 1.0e-8)
+
+
+def density(
+    T: npt.ArrayLike,
+    S: npt.ArrayLike,
+    P: npt.ArrayLike,
+    lon: npt.ArrayLike = 0,
+    lat: npt.ArrayLike = 0,
+) -> np.ndarray:
+    """In-situ density of seawater [kg/m³] via TEOS-10.
+
+    Parameters
+    ----------
+    T : float or array_like
+        In-situ temperature [°C].
+    S : float or array_like
+        Practical salinity [PSU].
+    P : float or array_like
+        Pressure [dbar].
+    lon, lat : float or array_like
+        Longitude [°E] / latitude [°N] for the TEOS-10 Absolute-Salinity
+        composition anomaly. Default: 0. Immaterial at typical depths; pass the
+        cast position for consistency.
+
+    Returns
+    -------
+    rho : float or ndarray
+        In-situ density [kg/m³].
+    """
+    import gsw
+
+    SA = gsw.SA_from_SP(S, P, lon, lat)
+    CT = gsw.CT_from_t(SA, T, P)
+    return gsw.rho(SA, CT, P)
+
+
+def buoyancy_freq(
+    T: npt.ArrayLike,
+    S: npt.ArrayLike,
+    P: npt.ArrayLike,
+    lat: float = 0,
+    min_dp: float = 1e-4,
+    lon: npt.ArrayLike = 0,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Buoyancy frequency squared N² [s⁻²] from profiles.
+
+    Parameters
+    ----------
+    T : array_like
+        In-situ temperature profile [°C].
+    S : array_like
+        Practical salinity profile [PSU].
+    P : array_like
+        Pressure profile [dbar].
+    lat : float
+        Latitude [°N]. Default: 0. N² is scaled by the latitude-dependent
+        gravitational acceleration g(lat) inside ``gsw.Nsquared``; away from
+        the equator this matters (≈0.9% bias at 70°N), so supply the cast
+        latitude rather than relying on the equatorial default.
+    min_dp : float
+        Minimum adjacent pressure spacing [dbar]; pairs with smaller spacing
+        yield NaN instead of a spurious ``inf`` from the dp=0 division.
+        Default: 1e-4.
+    lon : float or array_like
+        Longitude [°E] for the TEOS-10 Absolute-Salinity composition anomaly
+        (threaded into ``SA_from_SP`` alongside ``lat``). Default: 0.
+
+    Returns
+    -------
+    N2 : ndarray
+        Buoyancy frequency squared [s⁻²], length len(P)-1.
+    p_mid : ndarray
+        Mid-point pressures [dbar], length len(P)-1.
+    """
+    import gsw
+
+    # Defect (audit 103): lat=0 silently uses equatorial gravity, biasing N²
+    # for non-equatorial casts. Warn once so the caller knows lat matters.
+    if lat == 0:
+        import warnings
+
+        warnings.warn(
+            "buoyancy_freq called with lat=0 (equatorial gravity); N² is "
+            "gravity-scaled, so supply the cast latitude for non-equatorial "
+            "data to avoid a systematic N² bias.",
+            stacklevel=2,
+        )
+
+    # Thread the cast lat/lon into Absolute Salinity too (not just the gravity
+    # scaling below), so the composition anomaly is consistent.  The anomaly is
+    # tiny at typical depths (~1e-3 g/kg), so this is correctness hygiene, not a
+    # material change; production N2 (processing/mixing.py) already passes lon/lat.
+    SA = gsw.SA_from_SP(S, P, lon, lat)
+    CT = gsw.CT_from_t(SA, T, P)
+    N2, p_mid = gsw.Nsquared(SA, CT, P, lat)
+    # Defect (audit 104): gsw.Nsquared divides by adjacent dp; duplicate or
+    # non-monotonic pressures (common in binned/turn-around data) give a silent
+    # inf. Replace degenerate-spacing entries with NaN, matching mixing.py.
+    dp = np.diff(np.asarray(P, dtype=float))
+    N2 = np.where(np.abs(dp) < min_dp, np.nan, N2)
+    return N2, p_mid