quantmet-tools 0.4.4__py3-none-any.whl

quantmet/helmholtz.py

@@ -0,0 +1,161 @@
+"""Global Helmholtz decomposition by spherical-harmonic Poisson inversion.
+
+Given u, v on the sphere, compute divergence and vorticity, invert the
+Laplacian spectrally (chi_lm = -a^2 delta_lm / l(l+1); psi_lm likewise from
+vorticity), and return velocity potential / streamfunction plus the
+irrotational (divergent) and nondivergent wind components.
+
+Implementation notes that matter in practice:
+- Wind is sampled on a Gauss-Legendre (GLQ) grid before differentiating, so
+  there are no pole points and no 1/cos(phi) blowups in the divergence.
+- The l=0 mode is excluded (undefined for the inverse Laplacian).
+- cos(phi) is clipped when evaluating grad(chi) near the poles of the
+  output Driscoll-Healy grid.
+- The input is wrapped in longitude (a column at lon + 360 and one at
+  lon - 360) and, if it lacks them, given pole rows before it is interpolated
+  to the GLQ grid, so any regular global grid works at any lmax. (Before
+  0.3.1 a 1.5 or 2.5 deg grid at lmax = 120 left the GLQ columns past its
+  last longitude NaN, and chi came out entirely NaN.)
+- Longitude derivatives are periodic centred differences on every global
+  grid (GLQ and the extended DH2 output, whose 360 column repeats 0); before
+  0.3.1 np.gradient's one-sided differences were used at the seam columns.
+
+Powers the Walker-circulation monitor at https://scorvec.com/circulation.html
+(velocity potential of the 200 hPa divergent wind, and the zonal mass
+streamfunction built from the divergent zonal wind), and supplies the
+streamfunction for the wave-activity flux (quantmet.waf).
+
+Accuracy: vorticity and divergence are second-order finite differences on
+the GLQ grid, so the inversion error falls roughly as lmax^-1.7 (solid-body
+rotation: 2.5 % at lmax = 31, 0.8 % at 63, 0.24 % at 127).
+
+The output grid is pyshtools' extended Driscoll-Healy grid: it includes
+both poles and repeats longitude 0 at 360.
+
+Requires: pyshtools, xarray.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import xarray as xr
+import pyshtools as pysh
+
+from .constants import A_EARTH
+
+__all__ = ["velocity_potential", "streamfunction", "irrotational_wind", "nondivergent_wind"]
+
+
+def _to_0360(da: xr.DataArray) -> xr.DataArray:
+    """Longitudes mapped to [0, 360) and sorted (a repeated seam column dropped); latitudes ascending."""
+    lon = np.mod(da["longitude"].values.astype(float), 360.0)
+    da = da.assign_coords(longitude=lon).sortby("longitude")
+    keep = np.r_[True, np.diff(da["longitude"].values) > 1e-9]
+    return da.isel(longitude=np.flatnonzero(keep)).sortby("latitude")
+
+
+def _pole_row(row: np.ndarray) -> np.ndarray:
+    """A wind component at a pole: only zonal wavenumber 1 of the nearest row survives (a cross-polar flow seen in
+    local east/north components), so that is what the pole row gets."""
+    c = np.fft.rfft(row)
+    keep = np.zeros_like(c)
+    keep[1:2] = c[1:2]
+    return np.fft.irfft(keep, n=row.size)
+
+
+def _padded(da: xr.DataArray) -> xr.DataArray:
+    """Wrap one column each side in longitude, and add pole rows if the grid stops short of the poles, so that
+    interpolation to any GLQ grid stays inside the data."""
+    lon = da["longitude"].values
+    da = xr.concat(
+        [
+            da.isel(longitude=[-1]).assign_coords(longitude=[lon[-1] - 360.0]),
+            da,
+            da.isel(longitude=[0]).assign_coords(longitude=[lon[0] + 360.0]),
+        ],
+        dim="longitude",
+    )
+    da = da.transpose("latitude", "longitude")
+    lat = da["latitude"].values
+    rows, lats = [], []
+    if lat[0] > -90.0 + 1e-9:
+        rows.append(_pole_row(da.values[0])[None])
+        lats.append([-90.0])
+    rows.append(da.values)
+    lats.append(lat)
+    if lat[-1] < 90.0 - 1e-9:
+        rows.append(_pole_row(da.values[-1])[None])
+        lats.append([90.0])
+    return xr.DataArray(
+        np.concatenate(rows, 0),
+        dims=("latitude", "longitude"),
+        coords={"latitude": np.concatenate(lats), "longitude": da["longitude"].values},
+    )
+
+
+def _ddlon(f: np.ndarray, lon_deg) -> np.ndarray:
+    """d f / d lambda (per radian) along the last axis: periodic centred differences on a global uniform grid (with
+    or without a repeated 360 column), np.gradient on a regional one."""
+    lon = np.asarray(lon_deg, float)
+    d = np.diff(lon)
+    dl = d.mean()
+    if np.allclose(d, dl, rtol=1e-6, atol=1e-9):
+        dlr = np.deg2rad(dl)
+        span = lon[-1] - lon[0]
+        if np.isclose(span, 360.0, atol=1e-6):  # repeated seam column (DH2 extended grid)
+            core = f[..., :-1]
+            g = (np.roll(core, -1, axis=-1) - np.roll(core, 1, axis=-1)) / (2 * dlr)
+            return np.concatenate([g, g[..., :1]], axis=-1)
+        if np.isclose(span + dl, 360.0, atol=1e-6):  # full circle, no repeat (GLQ)
+            return (np.roll(f, -1, axis=-1) - np.roll(f, 1, axis=-1)) / (2 * dlr)
+    return np.gradient(f, np.deg2rad(lon), axis=-1)
+
+
+def _laplace_invert(field: np.ndarray, lmax: int) -> pysh.SHGrid:
+    clm = pysh.SHGrid.from_array(field, grid="GLQ").expand()
+    l = np.arange(clm.lmax + 1, dtype=float)
+    fac = np.zeros_like(l)
+    fac[1:] = -(A_EARTH**2) / (l[1:] * (l[1:] + 1))
+    out = clm.copy()
+    out.coeffs *= fac[None, :, None]
+    return out.expand(grid="DH2")
+
+
+def _grid_uv(u2d: xr.DataArray, v2d: xr.DataArray, lmax: int):
+    u2d, v2d = _padded(_to_0360(u2d)), _padded(_to_0360(v2d))
+    glat, glon = pysh.expand.GLQGridCoord(lmax)
+    ug = u2d.interp(latitude=glat, longitude=glon).values
+    vg = v2d.interp(latitude=glat, longitude=glon).values
+    return ug, vg, np.deg2rad(glat), np.deg2rad(glon)
+
+
+def velocity_potential(u2d: xr.DataArray, v2d: xr.DataArray, lmax: int = 120):
+    """chi (m^2/s) with its output-grid lats/lons: inverts del^2 chi = div."""
+    ug, vg, latr, lonr = _grid_uv(u2d, v2d, lmax)
+    cosp = np.cos(latr)[:, None]
+    div = (_ddlon(ug, np.rad2deg(lonr)) + np.gradient(vg * cosp, latr, axis=0)) / (A_EARTH * cosp)
+    g = _laplace_invert(div, lmax)
+    return g.data, np.array(g.lats()), np.array(g.lons())
+
+
+def streamfunction(u2d: xr.DataArray, v2d: xr.DataArray, lmax: int = 120):
+    """psi (m^2/s): inverts del^2 psi = zeta (relative vorticity)."""
+    ug, vg, latr, lonr = _grid_uv(u2d, v2d, lmax)
+    cosp = np.cos(latr)[:, None]
+    zeta = (_ddlon(vg, np.rad2deg(lonr)) - np.gradient(ug * cosp, latr, axis=0)) / (A_EARTH * cosp)
+    g = _laplace_invert(zeta, lmax)
+    return g.data, np.array(g.lats()), np.array(g.lons())
+
+
+def irrotational_wind(chi: np.ndarray, dlat: np.ndarray, dlon: np.ndarray):
+    """(u_chi, v_chi) = grad(chi) on the chi grid (periodic in longitude on a global grid)."""
+    latr = np.deg2rad(dlat)
+    cosp = np.clip(np.cos(latr), 1e-3, None)[:, None]
+    return (_ddlon(chi, dlon) / (A_EARTH * cosp), np.gradient(chi, latr, axis=0) / A_EARTH)
+
+
+def nondivergent_wind(psi: np.ndarray, dlat: np.ndarray, dlon: np.ndarray):
+    """(u_psi, v_psi) = k x grad(psi) on the psi grid (periodic in longitude on a global grid)."""
+    latr = np.deg2rad(dlat)
+    cosp = np.clip(np.cos(latr), 1e-3, None)[:, None]
+    return (-np.gradient(psi, latr, axis=0) / A_EARTH, _ddlon(psi, dlon) / (A_EARTH * cosp))

quantmet/packets.py

@@ -0,0 +1,51 @@
+"""Rossby wave-packet envelope (Zimin, Szunyogh, Patil, Hunt & Ott 2003, MWR 131).
+
+The envelope of the meridional wind along each latitude circle: keep zonal wavenumbers kmin..kmax, build the analytic
+signal (positive wavenumbers doubled, negative zeroed, so the real part is the band-passed field) and take its modulus.
+A train of troughs and ridges then reads as ONE positive hump instead of alternating signs, so a longitude-time
+(Hovmoller) plot of the envelope shows a wave packet as a single bright streak whose slope is the group velocity.
+
+Implementation notes that matter in practice:
+- The band matters: kmin ~4 removes the planetary stationary waves (whose envelope is just "everywhere"), kmax ~15
+  removes grid-scale noise. Zimin et al. use 4-17 for 300 hPa v.
+- The transform is along longitude only, latitude by latitude; average the ENVELOPE over a latitude band (not v),
+  since v changes sign across a packet's meridional structure.
+- For the analytic signal to be meaningful the band must be well inside (0, n/2); the function checks it.
+
+Powers the wave-packet panel of the tropical-cyclone / jet-stream card at https://scorvec.com/circulation.html.
+
+Requires: numpy only.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["packet_envelope", "band_mean"]
+
+
+def packet_envelope(v: np.ndarray, kmin: int = 4, kmax: int = 15) -> np.ndarray:
+    """Envelope (same units as v) of v(..., lon) for zonal wavenumbers kmin..kmax; the LAST axis is longitude and must
+    span the full circle with uniform spacing. NaNs are treated as zero."""
+    v = np.nan_to_num(np.asarray(v, float))
+    n = v.shape[-1]
+    if not (1 <= kmin <= kmax < n // 2):
+        raise ValueError(f"need 1 <= kmin <= kmax < nlon/2 (got {kmin}, {kmax}, nlon {n})")
+    F = np.fft.fft(v, axis=-1)
+    Z = np.zeros_like(F)
+    Z[..., kmin : kmax + 1] = 2.0 * F[..., kmin : kmax + 1]
+    return np.abs(np.fft.ifft(Z, axis=-1))
+
+
+def band_mean(field: np.ndarray, lat: np.ndarray, lat_min: float, lat_max: float, lat_axis: int = -2) -> np.ndarray:
+    """cos(lat)-weighted mean of field over lat_min..lat_max along ``lat_axis`` (removed from the output)."""
+    field = np.asarray(field, float)
+    lat = np.asarray(lat, float)
+    m = (lat >= lat_min) & (lat <= lat_max)
+    if not m.any():
+        raise ValueError("no latitudes in the band")
+    w = np.cos(np.deg2rad(lat[m]))
+    sub = np.compress(m, field, axis=lat_axis)
+    shape = [1] * sub.ndim
+    shape[lat_axis] = -1
+    return (sub * w.reshape(shape)).sum(axis=lat_axis) / w.sum()

quantmet/pv.py

@@ -0,0 +1,143 @@
+"""Ertel potential vorticity on pressure levels, the dynamic tropopause, and isentropic PV.
+
+    PV = -g [ (zeta + f) d(theta)/dp - (dv/dp)(d(theta)/dx) + (du/dp)(d(theta)/dy) ]      (PVU = 1e-6 K m^2 kg^-1 s^-1)
+
+computed on the pressure grid from T, u, v snapshots (lev, lat, lon) on a regular, global-in-longitude
+latitude-longitude grid. The dynamic tropopause (DT) is the 2-PVU surface; theta, p and the wind on it are found by
+searching UPWARD from the lowest level and interpolating linearly in PV between the bracketing levels (p in ln p).
+Isentropic PV interpolates linearly in theta.
+
+Implementation notes that matter in practice:
+- Pressure derivatives use np.gradient on the ACTUAL pressure levels (second order on a non-uniform grid);
+  horizontal derivatives are centred, periodic in longitude.
+- PV does not survive ensemble averaging: a mean of fifty tropopause folds is a smear, so compute it per member
+  (or on one member) and never on the ensemble-mean fields.
+- A light 3-point smoothing in each horizontal direction (``smooth=True``, the default) tames the grid-scale noise of
+  zeta on a 0.25 deg grid; turn it off for coarse grids or analysis work.
+- Where a column never reaches the threshold (the deep tropics, when the data stop at 100 hPa) the tropopause is at or
+  above the top level. ``dynamic_tropopause`` then returns the TOP-level values (a lower bound on theta, flagged in
+  ``never``) instead of a hole -- set ``fill_top=False`` to get NaN there.
+- The upward search takes the FIRST crossing, so a stratospheric intrusion folded under tropospheric air (a
+  tropopause fold) is found at its lower edge; that is the conventional DT choice.
+
+Powers the dynamic-tropopause loops (theta on 2 PVU, PV on 330/350 K) at https://scorvec.com/circulation.html.
+
+References: Hoskins, McIntyre & Robertson (1985, QJRMS); Morgan & Nielsen-Gammon (1998, MWR) on DT maps.
+
+Requires: numpy only.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .constants import A_EARTH, KAPPA, OMEGA, P0
+from .constants import G as G0
+
+__all__ = ["potential_temperature", "ertel_pv", "dynamic_tropopause", "on_isentrope"]
+
+
+def potential_temperature(t: np.ndarray, p_pa: np.ndarray) -> np.ndarray:
+    """theta (K) from T (K) on levels p_pa (Pa) along axis 0."""
+    p = np.asarray(p_pa, float).reshape((-1,) + (1,) * (np.ndim(t) - 1))
+    return np.asarray(t, float) * (P0 / p) ** KAPPA
+
+
+def ertel_pv(
+    t: np.ndarray, u: np.ndarray, v: np.ndarray, p_pa: np.ndarray, lat: np.ndarray, lon: np.ndarray, smooth: bool = True
+):
+    """Ertel PV (PVU) and theta (K) on the pressure grid for one time.
+
+    t, u, v : (lev, lat, lon); p_pa : (lev,) in Pa (any order, monotonic); lat, lon in degrees, regular, lon global
+    (periodic). Returns (pv, theta), both (lev, lat, lon). Southern-hemisphere PV is negative (f < 0)."""
+    t = np.asarray(t, float)
+    u = np.asarray(u, float)
+    v = np.asarray(v, float)
+    p_pa = np.asarray(p_pa, float)
+    th = potential_temperature(t, p_pa)
+    phi = np.deg2rad(np.asarray(lat, float))
+    lam = np.deg2rad(np.asarray(lon, float))
+    cosphi = np.clip(np.cos(phi), 1e-6, None)[None, :, None]
+    dlam = lam[1] - lam[0]
+
+    def ddx(a):
+        return (np.roll(a, -1, -1) - np.roll(a, 1, -1)) / (2 * dlam) / (A_EARTH * cosphi)
+
+    def ddy(a):
+        return np.gradient(a, phi, axis=1) / A_EARTH
+
+    zeta = ddx(v) - ddy(u * cosphi) / cosphi
+    f = (2 * OMEGA * np.sin(phi))[None, :, None]
+    th_p = np.gradient(th, p_pa, axis=0)
+    u_p = np.gradient(u, p_pa, axis=0)
+    v_p = np.gradient(v, p_pa, axis=0)
+    pv = -G0 * ((zeta + f) * th_p - v_p * ddx(th) + u_p * ddy(th)) * 1e6
+    if smooth:
+        pv = (pv + np.roll(pv, 1, -1) + np.roll(pv, -1, -1)) / 3.0
+        pv[:, 1:-1] = (pv[:, :-2] + pv[:, 1:-1] + pv[:, 2:]) / 3.0
+    return pv, th
+
+
+def _bottom_up(p_pa):
+    """Index order putting the highest pressure (lowest level) first."""
+    return np.argsort(-np.asarray(p_pa, float))
+
+
+def dynamic_tropopause(
+    pv: np.ndarray,
+    theta: np.ndarray,
+    u: np.ndarray,
+    v: np.ndarray,
+    p_pa: np.ndarray,
+    thr: float = 2.0,
+    fill_top: bool = True,
+) -> dict:
+    """theta, p (hPa), u, v on the ``thr``-PVU surface, searching upward from the lowest level.
+
+    Use |PV| (``np.abs(pv)``) for a both-hemisphere search. Returns a dict with 'theta', 'p', 'u', 'v' (lat, lon) and
+    'never' (bool: the column never reached thr; values there are the top level's if fill_top, else NaN)."""
+    o = _bottom_up(p_pa)
+    pv, th, u, v = (np.asarray(x, float)[o] for x in (pv, theta, u, v))
+    p = np.asarray(p_pa, float)[o]
+    above = pv >= thr
+    nl = pv.shape[0]
+    idx = np.argmax(above, axis=0)
+    never = ~above.any(axis=0)
+    k1 = np.clip(idx, 1, nl - 1)
+    k0 = k1 - 1
+    jj, ii = np.meshgrid(np.arange(pv.shape[1]), np.arange(pv.shape[2]), indexing="ij")
+    pv0, pv1 = pv[k0, jj, ii], pv[k1, jj, ii]
+    w = np.clip((thr - pv0) / np.where(np.abs(pv1 - pv0) < 1e-6, 1e-6, pv1 - pv0), 0, 1)
+    w = np.where(idx == 0, 0.0, w)  # already above thr at the lowest level: that level itself
+    k0 = np.where(idx == 0, 0, k0)
+    k1 = np.where(idx == 0, 0, k1)
+
+    def interp(a):
+        return a[k0, jj, ii] * (1 - w) + a[k1, jj, ii] * w
+
+    lnp = np.log(p)[:, None, None] * np.ones_like(pv)
+    out = {"theta": interp(th), "p": np.exp(interp(lnp)) / 100.0, "u": interp(u), "v": interp(v)}
+    top = {"theta": th[-1], "p": np.full(th.shape[1:], p[-1] / 100.0), "u": u[-1], "v": v[-1]}
+    for k in out:
+        out[k] = np.where(never, top[k] if fill_top else np.nan, out[k])
+    out["never"] = never
+    return out
+
+
+def on_isentrope(pv: np.ndarray, theta: np.ndarray, u: np.ndarray, v: np.ndarray, theta0: float) -> dict:
+    """PV and wind interpolated linearly in theta onto the theta0 isentrope; NaN where theta0 is outside the column.
+    Assumes theta increases monotonically with height (statically stable); levels in any order."""
+    th = np.asarray(theta, float)
+    o = np.argsort(th.mean(axis=(1, 2)))  # theta ascending = upward
+    pv, th, u, v = (np.asarray(x, float)[o] for x in (pv, th, u, v))
+    nl = pv.shape[0]
+    idx = np.clip(np.sum(th <= theta0, axis=0) - 1, 0, nl - 2)
+    jj, ii = np.meshgrid(np.arange(pv.shape[1]), np.arange(pv.shape[2]), indexing="ij")
+    t0, t1 = th[idx, jj, ii], th[idx + 1, jj, ii]
+    w = np.clip((theta0 - t0) / np.where(np.abs(t1 - t0) < 1e-3, 1e-3, t1 - t0), 0, 1)
+    valid = (th.min(axis=0) <= theta0) & (th.max(axis=0) >= theta0)
+
+    def interp(a):
+        return np.where(valid, a[idx, jj, ii] * (1 - w) + a[idx + 1, jj, ii] * w, np.nan)
+
+    return {"pv": interp(pv), "u": interp(u), "v": interp(v)}

quantmet/qbo.py

@@ -0,0 +1,112 @@
+"""The QBO zero-wind line: where the zonal-mean zonal wind turns easterly on
+the equatorward side of the winter westerlies.
+
+Holton and Tan (1980): planetary waves propagating up and equatorward from
+the winter midlatitudes meet a critical line where [u] = 0. With easterly
+QBO winds in the lower stratosphere that line sits in the winter
+subtropics, the extratropical waveguide narrows and more wave activity is
+steered toward the polar vortex. zero_line tracks WHERE the line is, one
+latitude per profile, so it can be followed day by day, level by level and
+member by member.
+
+The rule (defaults are the site's, chosen on robustness before looking at
+any vortex relation):
+  1. Smooth [u] in latitude with a Gaussian of `sigma` degrees.
+  2. Start at the strongest westerlies between start = (25, 45) degrees in
+     the hemisphere asked for. If even that maximum is <= 0 there are no
+     winter westerlies to bound: undefined, flag 1 (most of May-September in
+     the NH).
+  3. Scan toward and across the equator. The index is the first zero
+     crossing (linear interpolation) whose easterly region beyond it reaches
+     at least `umin` (1 m/s).
+  4. No qualifying crossing before `bound` degrees in the other hemisphere:
+     censored at -bound, flag 2.
+
+Numerical notes that matter in practice:
+- THE DIP RULE. A zero crossing is only a critical line if the easterlies
+  beyond it are real. Shallow dips (min |u| < umin, inside analysis noise)
+  are stepped over and the scan continues past them: without that, a
+  -0.3 m/s wobble at 18N in a westerly-QBO autumn reads as a critical line
+  and the index jumps 20 degrees for a day. The smoothing alone does not fix
+  it (a dip wider than sigma survives), and raising sigma blurs the real
+  line; the amplitude test is what separates them.
+- CENSORING IS INFORMATION. With westerly QBO winds at a level there may be
+  no easterlies anywhere within reach; that is flag 2 at -bound, not a
+  missing value, and statistics must treat it as a censored observation.
+- SOUTHERN HEMISPHERE by mirroring the grid: the SH index is the NH rule on
+  -lat, returned negative (positive = north throughout).
+
+Powers the QBO zero-wind-line tracker on
+https://scorvec.com/stratosphere.html (MERRA-2 reference, GEOS FP analyses
+and per-member AIFS-ENS / IFS-ENS forecasts).
+
+Requires: numpy, scipy (Gaussian smoothing).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+SIGMA, UMIN, START, BOUND = 2.0, 1.0, (25.0, 45.0), 45.0
+
+__all__ = ["zero_line", "SIGMA", "UMIN", "START", "BOUND"]
+
+
+def zero_line(u, lat, hemi: str = "nh", sigma: float = SIGMA, umin: float = UMIN, start=START, bound: float = BOUND):
+    """Zero-wind-line latitude of [u] profiles.
+
+    u     : (..., lat) zonal-mean zonal wind, m/s; lat in any order, uniformly
+            spaced (degrees).
+    hemi  : "nh" or "sh", the winter hemisphere whose westerlies bound it.
+    Returns (index, flag), both with u's leading shape: index in degrees
+    (positive north; NaN where flag == 1, -bound / +bound where censored),
+    flag 0 = found, 1 = undefined (no westerlies to bound), 2 = censored."""
+    from scipy.ndimage import gaussian_filter1d
+
+    if hemi not in ("nh", "sh"):
+        raise ValueError("hemi must be 'nh' or 'sh'")
+    lat = np.asarray(lat, float)
+    u = np.asarray(u, float)
+    o = np.argsort(lat)
+    lat, u = lat[o], u[..., o]
+    if hemi == "sh":
+        lat, u = -lat[::-1], u[..., ::-1]
+    if sigma > 0:
+        u = gaussian_filter1d(u, sigma / abs(lat[1] - lat[0]), axis=-1, mode="nearest")
+    shp = u.shape[:-1]
+    U = u.reshape(-1, u.shape[-1])
+    keep = lat >= -bound
+    la, U = lat[keep], U[:, keep]
+    st = np.flatnonzero((la >= start[0]) & (la <= start[1]))
+    if st.size == 0:
+        raise ValueError("no grid latitude inside `start`")
+    z = np.full(U.shape[0], np.nan)
+    fl = np.zeros(U.shape[0], int)
+    for k in range(U.shape[0]):
+        row = U[k]
+        if not np.isfinite(row).all():
+            fl[k] = 1
+            continue
+        j = st[np.argmax(row[st])]
+        if row[j] <= 0:
+            fl[k] = 1
+            continue
+        found = False
+        while j > 0:
+            if row[j - 1] <= 0 < row[j]:
+                jj = j - 1
+                while jj >= 0 and row[jj] <= 0:
+                    jj -= 1
+                if row[jj + 1 : j].min() <= -umin:  # deep enough: a critical line
+                    z[k] = la[j - 1] + (la[j] - la[j - 1]) * (0 - row[j - 1]) / (row[j] - row[j - 1])
+                    found = True
+                    break
+                if jj < 0:
+                    break
+                j = jj + 1  # shallow dip: step over it
+                continue
+            j -= 1
+        if not found:
+            z[k], fl[k] = -bound, 2
+    z = z.reshape(shp)
+    return (-z if hemi == "sh" else z), fl.reshape(shp)