wavespectra 4.7.0__tar.gz → 4.9.0__tar.gz

{wavespectra-4.7.0 → wavespectra-4.9.0}/AUTHORS.rst

@@ -26,9 +26,11 @@ Contributors
 
 * `Matthew Iannucci`_
 * `Carlos A. Michelén Ströfer`_
+* `eddylr`_
 * `Henrique Rapizo`_
 * `John Harrington`_
 * `Jorge Perez`_
+* `Joris de Vroom`_
 * `Paul Branson`_
 * `Ruben de Bruin`_
 * `Ryan Coe`_
@@ -36,9 +38,11 @@ Contributors
 
 .. _`Matthew Iannucci`: https://github.com/mpiannucci
 .. _`Carlos A. Michelén Ströfer`: https://github.com/cmichelenstrofer
+.. _`eddylr`: https://github.com/eddylr
 .. _`Henrique Rapizo`: https://github.com/hrapizo
 .. _`John Harrington`: https://github.com/JohnCHarrington
 .. _`Jorge Perez`: https://github.com/jorgeperezg
+.. _`Joris de Vroom`: https://github.com/jdevroom
 .. _`Paul Branson`: https://github.com/pbranson
 .. _`Ruben de Bruin`: https://github.com/RubendeBruin
 .. _`Ryan Coe`: https://github.com/ryancoe

{wavespectra-4.7.0/wavespectra.egg-info → wavespectra-4.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavespectra
-Version: 4.7.0
+Version: 4.9.0
 Summary: Library for ocean wave spectra
 Author-email: Wavespectra Developers <r.guedes@oceanum.science>
 Maintainer-email: Rafael Guedes <r.guedes@oceanum.science>, Tom Durrant <t.durrant@oceanum.science>
@@ -42,6 +42,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
@@ -49,6 +50,7 @@ License-File: AUTHORS.rst
 Requires-Dist: click
 Requires-Dist: dask
 Requires-Dist: matplotlib
+Requires-Dist: numpy
 Requires-Dist: python-dateutil
 Requires-Dist: pyyaml
 Requires-Dist: sortedcontainers

{wavespectra-4.7.0 → wavespectra-4.9.0}/pyproject.toml

@@ -30,12 +30,14 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 requires-python = ">=3.9"
 dependencies = [
     "click",
     "dask",
     "matplotlib",
+    "numpy",
     "python-dateutil",
     "pyyaml",
     "sortedcontainers",
@@ -99,8 +101,6 @@ docs = [
 ]
 
 [tool.setuptools.packages.find]
-# Explicit include so stray top-level directories created at build time
-# (e.g. cibuildwheel's wheelhouse/) don't break flat-layout auto-discovery.
 include = ["wavespectra*"]
 
 [tool.setuptools.package-data]
@@ -112,15 +112,9 @@ include = ["wavespectra*"]
 version = {attr = "wavespectra.__version__"}
 
 [tool.cibuildwheel]
-# CPython versions matching the supported range in the classifiers.
-build = ["cp39-*", "cp310-*", "cp311-*", "cp312-*", "cp313-*"]
-# 64-bit only: 32-bit Windows wheels would be built by default, but core
-# dependencies (e.g. matplotlib) no longer ship win32 wheels to test against.
+build = ["cp39-*", "cp310-*", "cp311-*", "cp312-*", "cp313-*", "cp314-*"]
 archs = ["auto64"]
-# Skip musl-based linux; can be added later if there is demand.
 skip = ["*-musllinux*"]
-# Test every built wheel by running the partition test module, which
-# exercises the compiled specpart extension end to end.
 test-requires = ["pytest", "netCDF4"]
 test-command = "pytest {project}/tests/test_partition.py -q"
 build-verbosity = 1
@@ -128,9 +122,6 @@ build-verbosity = 1
 [tool.pytest.ini_options]
 norecursedirs = [".*", "build", "dist", "CVS", "_darcs", "{arch}", "*.egg", "venv", "broken"]
 filterwarnings = [
-    # netCDF4-python sets the .shape attribute on numpy arrays, which numpy
-    # 2.5 deprecated; it surfaces through xarray's netCDF4 backend whenever a
-    # netCDF file is written. Third-party issue, nothing to fix in wavespectra.
     "ignore:Setting the shape on a NumPy array has been deprecated:DeprecationWarning",
 ]
 
@@ -143,9 +134,9 @@ indent-style = "space"
 line-ending = "auto"
 
 [tool.ruff.lint]
-# B015/B018: flag comparisons/expressions whose result is discarded, which in
-# tests almost always means a forgotten `assert`.
-extend-select = ["B015", "B018"]
+# Pin the rule set explicitly so linting does not change with the ruff release.
+# E4, E7, E9 and F were the defaults up to ruff 0.15.
+select = ["E4", "E7", "E9", "F", "B015", "B018"]
 
 [tool.ruff.lint.extend-per-file-ignores]
 "wavespectra/__init__.py" = ["F401"]
@@ -173,7 +164,7 @@ extend-select = ["B015", "B018"]
 github_url = "https://github.com/wavespectra/wavespectra/"
 
 [tool.tbump.version]
-current = "4.7.0"
+current = "4.9.0"
 regex = '''
   (?P<major>\d+)
   \.(?P<minor>\d+)

{wavespectra-4.7.0 → wavespectra-4.9.0}/tests/test_partition.py

@@ -1,23 +1,31 @@
 import pytest
 from pathlib import Path
 import numpy as np
+import xarray as xr
 
 import wavespectra
 from wavespectra import read_ww3
+from wavespectra.construct import construct_partition
 from wavespectra.partition.partition import (
+    DEFAULTS,
     Partition,
     np_ptm1,
     np_ptm2,
     np_ptm3,
+    np_steepness,
     np_hp01,
 )
-from wavespectra.core.utils import waveage
+from wavespectra.core.utils import waveage, create_frequencies, to_coords
 from wavespectra.core import npstats
 from wavespectra.partition.tracking import track_partitions
 
 
 HERE = Path(__file__).parent
 
+# Well resolved spectral grid for constructing synthetic spectra
+FREQ = to_coords(create_frequencies(0.03, 40, 1.1), "freq")
+DIR = to_coords(np.arange(0, 360, 10.0), "dir")
+
 
 @pytest.fixture(autouse=True)
 def dataset_transforms():
@@ -374,6 +382,292 @@ class TestHP01(BasePTM):
         assert np.allclose(hs.values, self.dset.spec.hs().values, rtol=1e-2)
 
 
+class TestSteepness(BasePTM):
+    def setup_class(self):
+        super().setup_class(self)
+        self.dpt = self.dset.isel(time=0, site=0).dpt.values
+        self.scut = 0.025
+        self.swells = 3
+
+    def _exec(self, **kwargs):
+        out = np_steepness(
+            spectrum=self.efth,
+            spectrum_smooth=self.efth,
+            freq=self.freq,
+            dir=self.dir,
+            dpt=kwargs.get("dpt", self.dpt),
+            scut=kwargs.get("scut", self.scut),
+            tail=kwargs.get("tail", False),
+            swells=kwargs.get("swells", self.swells),
+        )
+        return out
+
+    def test_defaults(self):
+        self.out = self._exec()
+        assert self.out.shape[0] == self.swells + 1
+        assert self.hs_full == pytest.approx(self.hs_from_partitions)
+
+    def test_default_swells_is_one(self):
+        """The default returns a single wind sea and a single swell."""
+        assert DEFAULTS["steepness_swells"] == 1
+        self.out = np_steepness(
+            spectrum=self.efth,
+            spectrum_smooth=self.efth,
+            freq=self.freq,
+            dir=self.dir,
+            dpt=self.dpt,
+        )
+        assert self.out.shape[0] == 2
+        assert self.hs_full == pytest.approx(self.hs_from_partitions)
+
+    def test_default_swells_is_one_class(self):
+        """The Partition wrapper defaults to one wind sea and one swell."""
+        dspart = self.pt.steepness(dpt=self.dset.dpt)
+        assert dspart.part.size == 2
+        hs_dspart = np.sqrt((dspart.spec.hs() ** 2).sum("part"))
+        assert np.allclose(hs_dspart.values, self.dset.spec.hs().values, rtol=1e-2)
+
+    def test_request_all_partitions(self):
+        self.out = self._exec(swells=None)
+        assert self.hs_full == pytest.approx(self.hs_from_partitions)
+
+    def test_request_all_partitions_class(self):
+        """swells=None detects the required number of partitions."""
+        dspart = self.pt.steepness(dpt=self.dset.dpt, swells=None)
+        hs_dspart = np.sqrt((dspart.spec.hs() ** 2).sum("part"))
+        assert np.allclose(hs_dspart.values, self.dset.spec.hs().values, rtol=1e-2)
+
+    def test_request_less_partitions(self):
+        swells = 1
+        self.out = self._exec(swells=swells)
+        assert len(self.out) == swells + 1
+
+    def test_partition_class(self):
+        swells = 2
+        self.out = self._exec(swells=swells)
+        dspart = self.pt.steepness(dpt=self.dset.dpt, swells=swells)
+        hs_dspart = np.sqrt(np.sum(dspart.isel(time=0, site=0).spec.hs().values ** 2))
+        assert hs_dspart == pytest.approx(self.hs_from_partitions, rel=1e-2)
+
+    def test_no_wind_required(self):
+        """The method runs from a DataArray with no wind or depth available."""
+        dspart = Partition(self.dset.efth).steepness(swells=2)
+        assert isinstance(dspart, xr.DataArray)
+        assert dspart.part.size == 3
+        assert bool((dspart.spec.hs() > 0).any())
+
+    def test_no_depth_deep_water_default(self):
+        """Depth is optional, the deep water approximation is used without it."""
+        deep = self._exec(dpt=np.nan)
+        prescribed = self._exec(dpt=1e5)
+        assert np.allclose(deep, prescribed)
+
+    def test_depth_makes_partitions_steeper(self):
+        """Shoaling in shallow water pushes more energy into the wind sea.
+
+        The steepness is evaluated with the local wavelength when the depth is
+        prescribed, so the same swell is classified as wind sea in shallow
+        enough water.
+        """
+        swell = construct_partition(
+            freq_kwargs=dict(freq=FREQ, fp=1 / 9.0, hs=2.0, gamma=3.3),
+            dir_kwargs=dict(dir=DIR, dm=270.0, dspr=25.0),
+        ).transpose("freq", "dir")
+
+        def hs_windsea(dpt):
+            out = np_steepness(
+                spectrum=swell.values,
+                spectrum_smooth=swell.values,
+                freq=FREQ.values,
+                dir=DIR.values,
+                dpt=dpt,
+                swells=2,
+            )
+            return npstats.hs(out[0], FREQ.values, DIR.values)
+
+        assert hs_windsea(np.nan) == 0.0
+        assert hs_windsea(15.0) == 0.0
+        assert hs_windsea(10.0) == pytest.approx(2.0, rel=1e-2)
+
+    def test_lower_threshold_grows_windsea(self):
+        """A lower scut threshold classifies more energy as wind sea."""
+        lo = self.pt.steepness(dpt=self.dset.dpt, scut=0.01, swells=2)
+        hi = self.pt.steepness(dpt=self.dset.dpt, scut=0.06, swells=2)
+        hs_sea_lo = lo.isel(part=0).spec.hs()
+        hs_sea_hi = hi.isel(part=0).spec.hs()
+        assert bool((hs_sea_lo >= hs_sea_hi).all())
+        assert bool((hs_sea_lo > hs_sea_hi).any())
+
+    def test_unreachable_threshold_leaves_no_windsea(self):
+        """Partition 0 is null when no partition reaches scut."""
+        dspart = self.pt.steepness(dpt=self.dset.dpt, scut=1.0, swells=2)
+        assert bool((dspart.isel(part=0).spec.hs() == 0).all())
+
+    def test_tail_grows_windsea(self):
+        """The tail correction recovers wind seas truncated by the freq grid.
+
+        The sample file frequency grid stops at 0.406 Hz so the light wind seas
+        in it are truncated and their steepness is underestimated.
+        """
+        assert self.freq[-1] < 0.5
+        notail = self.pt.steepness(dpt=self.dset.dpt, swells=2)
+        tail = self.pt.steepness(dpt=self.dset.dpt, swells=2, tail=True)
+        hs_sea_notail = notail.isel(part=0).spec.hs()
+        hs_sea_tail = tail.isel(part=0).spec.hs()
+        assert bool((hs_sea_tail >= hs_sea_notail).all())
+        assert bool((hs_sea_tail > hs_sea_notail).any())
+
+    def test_tail_inert_for_swells(self):
+        """The tail correction cannot turn a swell into a wind sea.
+
+        A watershed swell partition carries no energy at the last frequency so
+        the correction is inert for it.
+        """
+        efth = self._sea_and_swell()
+        kwargs = dict(
+            spectrum=efth.values,
+            spectrum_smooth=efth.values,
+            freq=FREQ.values,
+            dir=DIR.values,
+            swells=2,
+        )
+        notail = np_steepness(**kwargs, tail=False)
+        tail = np_steepness(**kwargs, tail=True)
+        assert notail[0][-1].sum() > 0  # wind sea reaches the last frequency
+        assert notail[1][-1].sum() == 0  # swell does not
+        assert np.array_equal(notail[1], tail[1])
+
+    @staticmethod
+    def _sea_and_swell():
+        """Steep 6s wind sea and gentle 14s swell, opposing directions."""
+        sea = construct_partition(
+            freq_kwargs=dict(freq=FREQ, fp=1 / 6.0, hs=2.5, gamma=3.3),
+            dir_kwargs=dict(dir=DIR, dm=90.0, dspr=25.0),
+        )
+        swell = construct_partition(
+            freq_kwargs=dict(freq=FREQ, fp=1 / 14.0, hs=1.5, gamma=3.3),
+            dir_kwargs=dict(dir=DIR, dm=270.0, dspr=15.0),
+        )
+        return (sea + swell).transpose("freq", "dir")
+
+    def test_sea_and_swell_are_recovered(self):
+        """A steep wind sea and a gentle swell are classified from steepness."""
+        efth = self._sea_and_swell()
+        out = np_steepness(
+            spectrum=efth.values,
+            spectrum_smooth=efth.values,
+            freq=FREQ.values,
+            dir=DIR.values,
+            swells=2,
+        )
+        hs_parts = [npstats.hs(part, FREQ.values, DIR.values) for part in out]
+        assert hs_parts[0] == pytest.approx(2.5, rel=1e-2)
+        assert hs_parts[1] == pytest.approx(1.5, rel=1e-2)
+        assert hs_parts[2] == 0.0
+
+    def test_smoothing(self):
+        swells = 2
+        ds_nosmoothing = self.pt.steepness(dpt=self.dset.dpt, swells=swells)
+        ds_smoothing = self.pt.steepness(dpt=self.dset.dpt, swells=swells, smooth=True)
+        assert not ds_nosmoothing.spec.hs().equals(ds_smoothing.spec.hs())
+
+
+class TestSteepnessSwellMerge:
+    """Coverage for `swell_merge`, exercising the path where more swells are
+    detected than the requested `swells` slots. The ww3file.nc fixture used by
+    TestSteepness never detects more than 3 swells so it can't reach this path;
+    a synthetic four-swell spectrum with no wind sea is built here instead.
+    """
+
+    def setup_class(self):
+        self.freq = np.linspace(0.03, 0.5, 40)
+        self.dir = np.linspace(0, 350, 36)
+        self.dpt = np.nan  # np_steepness's sentinel for "no depth" (deep water)
+
+        def peak(fp, hsig, dp, spread=15):
+            E = npstats.jonswap(self.freq, fp, hsig)
+            dfac = np.exp(-0.5 * ((self.dir - dp + 180) % 360 - 180) ** 2 / spread**2)
+            dfac = dfac / (dfac.sum() * (self.dir[1] - self.dir[0]))
+            return np.outer(E, dfac)
+
+        # Four distinct, gentle (sub-threshold) swell systems, all classified
+        # as swell rather than wind sea, so requesting fewer than 4 swell
+        # slots always exercises the merge path.
+        self.efth = (
+            peak(0.07, 1.8, 200)
+            + peak(0.09, 1.4, 260)
+            + peak(0.11, 1.0, 30)
+            + peak(0.14, 0.6, 100)
+        )
+        self.hs_full = npstats.hs(self.efth, self.freq, self.dir)
+
+    def _exec(self, swells, swell_merge):
+        return np_steepness(
+            spectrum=self.efth,
+            spectrum_smooth=self.efth,
+            freq=self.freq,
+            dir=self.dir,
+            dpt=self.dpt,
+            scut=0.025,
+            swells=swells,
+            swell_merge=swell_merge,
+        )
+
+    def _hs_from_partitions(self, out):
+        hs_partitions = [npstats.hs(efth, self.freq, self.dir) for efth in out]
+        return np.sqrt(np.sum(np.power(hs_partitions, 2)))
+
+    @pytest.mark.parametrize("swell_merge", ["sum", "hp01"])
+    @pytest.mark.parametrize("swells", [1, 2, 3])
+    def test_merge_conserves_energy_and_count(self, swells, swell_merge):
+        """Merging (either strategy) always yields exactly `swells` swell
+        partitions and loses no energy, unlike the old discard behaviour."""
+        out = self._exec(swells=swells, swell_merge=swell_merge)
+        assert out.shape[0] == swells + 1
+        assert self.hs_full == pytest.approx(self._hs_from_partitions(out), rel=1e-2)
+
+    def test_swells_one_merges_everything(self):
+        """swells=1 collapses every detected swell into the single output slot."""
+        out = self._exec(swells=1, swell_merge="sum")
+        assert out.shape[0] == 2
+        hs_swell = npstats.hs(out[1], self.freq, self.dir)
+        assert hs_swell == pytest.approx(self.hs_full, rel=1e-2)
+
+    def test_default_swell_merge_is_sum(self):
+        assert DEFAULTS["swell_merge"] == "sum"
+
+    def test_invalid_swell_merge_raises(self):
+        with pytest.raises(ValueError):
+            self._exec(swells=2, swell_merge="bogus")
+
+    def test_sum_and_hp01_can_disagree(self):
+        """The two strategies are free to group swells differently as long as
+        both conserve energy - sanity-check they actually differ on this
+        deliberately-ambiguous four-swell case rather than one silently
+        falling back to the other."""
+        hs_sum = sorted(
+            npstats.hs(e, self.freq, self.dir)
+            for e in self._exec(swells=2, swell_merge="sum")[1:]
+        )
+        hs_hp01 = sorted(
+            npstats.hs(e, self.freq, self.dir)
+            for e in self._exec(swells=2, swell_merge="hp01")[1:]
+        )
+        assert hs_sum != pytest.approx(hs_hp01)
+
+    def test_partition_class_default_merge(self):
+        """The Dataset-level `Partition.steepness()` wrapper defaults to the
+        same 'sum' merge behaviour as the numpy core function."""
+        ds = xr.Dataset(
+            {"efth": (("freq", "dir"), self.efth)},
+            coords={"freq": self.freq, "dir": self.dir},
+        )
+        dspart = ds.spec.partition.steepness(swells=2)
+        assert dspart.sizes["part"] == 3
+        hs_dspart = np.sqrt((dspart.spec.hs() ** 2).sum())
+        assert float(hs_dspart) == pytest.approx(self.hs_full, rel=1e-2)
+
+
 class TestBbox(BasePTM):
     def test_default(self):
         bboxes = [
@@ -441,6 +735,19 @@ class TestPartitionAndTrack(BasePTM):
         dspart = dspart.load()
         assert (dspart.ntracks.values > 0).all()
 
+    def test_track_steepness(self):
+        self._track("steepness", wspd=self.dset.wspd, dpt=self.dset.dpt)
+
+    def test_track_steepness_no_wind(self):
+        """Without wind the steepness partitions are matched as swells.
+
+        Wind variables are resolved from the dataset so partitioning from
+        the DataArray is required to exercise the no-wind path.
+        """
+        pt = Partition(self.dset.efth)
+        dspart = pt.track(method="steepness", swells=2).load()
+        assert (dspart.ntracks.values > 0).all()
+
     def test_track_hp01(self):
         self._track("hp01", wspd=self.dset.wspd, wdir=self.dset.wdir, dpt=self.dset.dpt)
 

{wavespectra-4.7.0 → wavespectra-4.9.0}/wavespectra/__init__.py

@@ -16,7 +16,7 @@ except ImportError as exc:
     warnings.warn(f"Cannot import accessors at the main module level:\n{exc}")
 
 
-__version__ = "4.7.0"
+__version__ = "4.9.0"
 
 
 def _import_functions(pkgname="input", prefix="read"):

{wavespectra-4.7.0 → wavespectra-4.9.0}/wavespectra/core/npstats.py

@@ -3,7 +3,7 @@
 import numpy as np
 from scipy.constants import g, pi
 
-from wavespectra.core.utils import R2D
+from wavespectra.core.utils import R2D, wavelen
 
 
 def mom1(spectrum, dir, theta=90.0):
@@ -27,19 +27,21 @@ def mom1(spectrum, dir, theta=90.0):
     return msin, mcos
 
 
-def dm(spectrum, dir):
+def dm(spectrum, dir, freq):
     """Mean wave direction Dm.
 
     Args:
-        - spectrum (2darray): wave spectrum array.
+        - spectrum (2darray): wave spectrum array E(f, d).
         - dir (1darray): wave direction array.
+        - freq (1darray): wave frequency array.
 
     Returns:
-        - dm (float): Mean spectral period.
+        - dm (float): Mean wave direction.
 
     """
     moms, momc = mom1(spectrum, dir)
-    dm = np.arctan2(moms.sum(axis=0), momc.sum(axis=0))
+    df = np.gradient(freq) if np.size(freq) > 1 else np.ones(1)
+    dm = np.arctan2((moms * df).sum(axis=0), (momc * df).sum(axis=0))
     dm = (270 - R2D * dm) % 360.0
     return dm
 
@@ -69,6 +71,49 @@ def hs(spectrum, freq, dir=None, tail=True):
     return 4.0 * np.sqrt(Etot)
 
 
+def steepness(spectrum, freq, dpt=None, tail=False):
+    """Wave steepness Hm0 / L evaluated at the energy period Tm-1,0.
+
+    Args:
+        - spectrum (1darray): Direction-integrated wave spectrum array E(f).
+        - freq (1darray): Wave frequency array.
+        - dpt (float): Water depth, deep water approximation used by default.
+        - tail (bool): If True, add the contribution of an f^-5 high-frequency
+          tail beyond the last frequency to the spectral moments.
+
+    Returns:
+        - steepness (float): Wave steepness Hm0 / L, used as the wind sea
+          criterion in the `steepness` partitioning method.
+
+    Note:
+        - The steepness of a fully developed Pierson-Moskowitz sea is 0.035 in
+          deep water regardless of the wind speed, and it increases as the sea
+          gets younger, so this is a wave age proxy that requires no wind input.
+        - The `tail` correction is applied to both m0 and m-1 so it is
+          consistent with the energy period. It matters for wind sea partitions
+          whose peak sits close to the upper limit of the frequency grid, which
+          are otherwise truncated and appear less steep than they are. Swell
+          partitions carry no energy at the last frequency so the correction is
+          inert for them.
+        - The steepness is evaluated with the local wavelength when `dpt` is
+          prescribed, so shoaling waves become steeper in shallow water.
+
+    """
+    df = np.abs(freq[1:] - freq[:-1])
+    add_tail = tail and freq[-1] > 0.333
+    m0 = 0.5 * np.sum(df * (spectrum[1:] + spectrum[:-1]))
+    if add_tail:
+        m0 += 0.25 * spectrum[-1] * freq[-1]
+    if m0 < 1e-6:
+        return 0.0
+    m_1 = 0.5 * np.sum(df * (spectrum[1:] / freq[1:] + spectrum[:-1] / freq[:-1]))
+    if add_tail:
+        m_1 += spectrum[-1] / 5.0
+    hm0 = 4.0 * np.sqrt(m0)
+    fm_10 = m0 / m_1
+    return float(hm0 / wavelen(fm_10, dpt))
+
+
 def dpm(ipeak, momsin, momcos):
     """Mean direction at the peak wave period Dpm.
 

{wavespectra-4.7.0 → wavespectra-4.9.0}/wavespectra/partition/partition.py

@@ -38,6 +38,9 @@ DEFAULTS = {
     "window": 3,
     "wscut": 0.3333,
     "agefac": 1.7,
+    "scut": 0.025,
+    "steepness_swells": 1,
+    "swell_merge": "sum",
 }
 
 
@@ -77,6 +80,11 @@ class Partition:
           freely propogating swell (i.e. unforced by the wind). This is similar to the
           method commonly used to generate wind-sea and swell from the WAM model.
         - ptm5: PTM5 splits spectra into wind sea and swell based on a user defined static cutoff.
+        - steepness: STEEPNESS works like PTM1 but identifies wind sea from the steepness Hm0 / L of each
+          topographic partition, evaluated at the energy period Tm-1,0, rather than from a wind speed and
+          direction based wave age criterion. Partitions at or above a minimum steepness are aggregated
+          and assigned to the wind-sea component and the remaining partitions are assigned as swell
+          components in order of decreasing wave height. No wind input is required.
         - hp01: HP01 partitions the spectra and merges wind-sea components as in the PTM1 method, then it combines
           adjacent swells belonging to the same wave system following the criteria outlined in Hanson and
           Phillips (2001) and Hanson et al. (2009). Useful for noisy measured spectra which the watershed
@@ -638,6 +646,169 @@ class Partition:
 
         return self._wrap_output(dsout.fillna(0.0))
 
+    def steepness(
+        self,
+        dpt=None,
+        scut=DEFAULTS["scut"],
+        tail=False,
+        swells=DEFAULTS["steepness_swells"],
+        swell_merge=DEFAULTS["swell_merge"],
+        smooth=DEFAULTS["smooth"],
+        freq_window=DEFAULTS["window"],
+        dir_window=DEFAULTS["window"],
+        ihmax=DEFAULTS["ihmax"],
+    ):
+        """STEEPNESS watershed partitioning.
+
+        STEEPNESS works like PTM1 but identifies wind sea from the steepness
+        Hm0 / L of each topographic partition, evaluated at the energy period
+        Tm-1,0, rather than from the wind speed and direction based wave age
+        criterion used by the other methods. Partitions with steepness at or
+        above `scut` are aggregated and assigned to the wind-sea component
+        (e.g., the first partition). The remaining partitions are assigned as
+        swell components in order of decreasing wave height, merged down to
+        `swells` partitions if more are detected (see `swell_merge`) so that no
+        swell energy is discarded. The default `swells=1` therefore returns a
+        single wind sea and a single swell holding all the non wind-sea energy.
+        Because no wind input is used, this method is useful when reliable wind
+        speed and direction are not available, or when the misalignment between
+        wave and wind direction is not a desired classification factor.
+
+        Args:
+            - dpt (xr.DataArray): Depth DataArray, taken from the `dpt` variable
+              in the underlying dataset if not provided, deep water approximation
+              used if not available from either source.
+            - scut (float): Wave steepness Hm0 / L cutoff, partitions with
+              steepness at or above this value are classified as wind sea.
+            - tail (bool): If True, account for an f^-5 high-frequency tail
+              beyond the last frequency when evaluating the steepness.
+            - swells (int): Number of swell partitions to compute, the default
+              of 1 merges all detected swells into a single partition. If None,
+              the number required to hold all swells detected from all spectra
+              is used, which doubles the compute time and triggers an eager
+              computation on dask datasets.
+            - swell_merge (str): How to reduce more than `swells` detected swells
+              down to `swells` partitions. "sum" (default) keeps the `swells - 1`
+              largest swells individually and adds the spectral energy of the
+              rest into the last (smallest) kept partition. "hp01" instead merges
+              excess swells onto their closest neighbour using the adjacency,
+              saddle-point and angle criteria from the `hp01` method (Hanson and
+              Phillips, 2001). Either way spectral energy is conserved rather
+              than discarded. Ignored if `swells` is None.
+            - smooth (bool): Compute watershed boundaries from smoothed spectra
+              as described in Portilla et al., 2009.
+            - freq_window (int): Size of running window for smoothing spectra.
+            - dir_window (int): Size of running window for smoothing spectra.
+            - ihmax (int): Number of discrete spectral levels in WW3 Watershed code.
+
+        Returns:
+            - dspart (xr.DataArray, xr.Dataset): Partitioned spectra with extra `part` dimension
+              where the 0th index are the wind sea and remaining indices are the swells
+              sorted by descending order of Hs.
+
+        Note:
+            - The steepness of a fully developed Pierson-Moskowitz sea is 0.035
+              in deep water regardless of the wind speed, and it grows as the sea
+              gets younger, so a single `scut` threshold applies across the
+              range of wind speeds. The default of 0.025 sits below the fully
+              developed value to allow for the energy a topographic partition
+              loses at its watershed boundaries.
+            - The steepness of a wind sea partition is underestimated when its
+              peak is close to the upper limit of the frequency grid, since the
+              truncated energy is missing from Hm0. This affects light wind seas
+              on the coarse frequency grids typical of wave model output, which
+              may then fall below `scut` and be classified as swell. Set
+              `tail=True` to compensate for the truncated energy; the correction
+              is inert for swell partitions, which carry no energy at the last
+              frequency.
+            - The steepness is evaluated with the local wavelength when the depth
+              is available, so shoaling waves become steeper in shallow water and
+              swells may be classified as wind sea on that basis alone. Prescribe
+              a larger `scut` or partition from the DataArray accessor without
+              a `dpt` argument to classify from the deep water steepness in
+              shallow water applications.
+
+        References:
+            - Hanson and Phillips (2001).
+            - Portilla et al. (2009).
+            - Tracy et al. (2007).
+            - Vincent et al. (1991).
+            - WW3 documentation (https://github.com/NOAA-EMC/WW3).
+
+        """
+        dpt = self._resolve(dpt, attrs.DEPNAME)
+        if dpt is None:
+            # Plain nan sentinel so apply_ufunc can broadcast it like the other
+            # scalar arguments; translated back to the deep water approximation
+            # inside np_steepness.
+            dpt = np.nan
+        if smooth:
+            dset_smooth = smooth_spec(self.dset, freq_window, dir_window)
+        else:
+            dset_smooth = self.dset
+
+        args = [
+            self.dset,
+            dset_smooth,
+            self.dset.freq,
+            self.dset.dir,
+            dpt,
+            scut,
+            tail,
+        ]
+        input_core_dims = [
+            ["freq", "dir"],
+            ["freq", "dir"],
+            ["freq"],
+            ["dir"],
+            [],
+            [],
+            [],
+            [],
+            [],
+            [],
+        ]
+
+        # Detect the number of swells required if not prescribed
+        if swells is None:
+            swells = self._detect_nparts(
+                np_steepness,
+                *args,
+                None,
+                swell_merge,
+                ihmax,
+                input_core_dims=input_core_dims,
+                nparts_fixed=1,
+            )
+
+        # Partitioning full spectra
+        dsout = xr.apply_ufunc(
+            np_steepness,
+            *args,
+            swells,
+            swell_merge,
+            ihmax,
+            input_core_dims=input_core_dims,
+            output_core_dims=[["part", "freq", "dir"]],
+            vectorize=True,
+            dask="parallelized",
+            output_dtypes=["float32"],
+            dask_gufunc_kwargs={
+                "allow_rechunk": True,
+                "output_sizes": {"part": swells + 1},
+            },
+        )
+
+        # Finalise output
+        dsout = self._set_metadata(dsout)
+        parts_description = {
+            "part0": "wind sea",
+            "part1-n": "swells in descending order of hs",
+        }
+        dsout.attrs.update(parts_description)
+
+        return self._wrap_output(dsout.transpose("part", ...))
+
     def hp01(
         self,
         wspd=None,
@@ -936,14 +1107,14 @@ class Partition:
 
         Args:
             - wspd (xr.DataArray): Wind speed DataArray, required by the ptm1
-              and ptm2 methods and optional for hp01. Taken from the `wspd`
-              variable in the underlying dataset if not provided.
+              and ptm2 methods and optional for hp01 and steepness. Taken from
+              the `wspd` variable in the underlying dataset if not provided.
             - wdir (xr.DataArray): Wind direction DataArray, as above.
             - dpt (xr.DataArray): Depth DataArray, as above.
             - method (str): Partitioning method to track partitions from,
-              one of "ptm1", "ptm2", "ptm3" or "hp01". The ptm4, ptm5 and bbox
-              methods define partitions as fixed spectral regions whose
-              identity is already continuous in time, so there is nothing
+              one of "ptm1", "ptm2", "ptm3", "steepness" or "hp01". The ptm4,
+              ptm5 and bbox methods define partitions as fixed spectral regions
+              whose identity is already continuous in time, so there is nothing
               to track.
             - ddpm_sea_max (float): Maximum peak direction difference for wind sea
               partitions. Default is 30 degrees.
@@ -963,8 +1134,8 @@ class Partition:
               must span to be included in the `systems=True` output. The
               default of 1 keeps all tracked systems.
             - kwargs: Further arguments passed to the partitioning method, e.g.
-              `swells`, `agefac`, `wscut`, `smooth` or the hp01 combining
-              parameters.
+              `swells`, `agefac`, `wscut`, `scut`, `smooth` or the
+              hp01 combining parameters.
 
         Returns:
             - dspart (xr.DataArray, xr.Dataset): Partitioned spectra with extra `part` dimension
@@ -977,11 +1148,14 @@ class Partition:
               in the `systems=False` output.
 
         Note:
-            - Wind sea partitions (partition 0 in ptm1 and hp01, partitions 0
-              and 1 in ptm2) are matched with wind-sea thresholds and the
-              remaining partitions with swell thresholds. The ptm3 partitions
-              are not classified and are all matched with swell thresholds,
-              which makes wind inputs optional for that method.
+            - Wind sea partitions (partition 0 in ptm1, hp01 and steepness,
+              partitions 0 and 1 in ptm2) are matched with wind-sea thresholds
+              and the remaining partitions with swell thresholds. The ptm3
+              partitions are not classified and are all matched with swell
+              thresholds, which makes wind inputs optional for that method.
+              The steepness method classifies the wind sea without wind but the
+              wind speed still defines the wind-sea matching threshold, so
+              without it all its partitions are matched with swell thresholds.
             - The time step is evaluated for each pair of consecutive spectra
               so records with gaps or irregular sampling use matching
               thresholds consistent with the actual time elapsed.
@@ -1014,10 +1188,15 @@ class Partition:
             # ptm3 partitions are not classified, tracking does not need wind
             wind_kwargs = {}
             nsea = 0
+        elif method == "steepness":
+            # steepness classifies the wind sea without wind, which is only
+            # required to match it with wind sea thresholds when tracking
+            wind_kwargs = {"dpt": dpt}
+            nsea = 1 if wspd is not None else 0
         else:
             raise ValueError(
-                f"Cannot track partitions from method '{method}', "
-                "available methods are 'ptm1', 'ptm2', 'ptm3' and 'hp01'"
+                f"Cannot track partitions from method '{method}', available "
+                "methods are 'ptm1', 'ptm2', 'ptm3', 'steepness' and 'hp01'"
             )
 
         # Do the partitioning, on the spectral variable only so the tracking
@@ -1125,6 +1304,117 @@ def np_ptm1(
     return np.array([wsea_partition] + swell_partitions)
 
 
+def np_steepness(
+    spectrum,
+    spectrum_smooth,
+    freq,
+    dir,
+    dpt=np.nan,
+    scut=DEFAULTS["scut"],
+    tail=False,
+    swells=DEFAULTS["steepness_swells"],
+    swell_merge=DEFAULTS["swell_merge"],
+    ihmax=DEFAULTS["ihmax"],
+):
+    """STEEPNESS spectra partitioning on numpy arrays.
+
+    Args:
+        - spectrum (2darray): Wave spectrum array with shape (nf, nd).
+        - spectrum_smooth (2darray): Smoothed wave spectrum array with shape (nf, nd).
+        - freq (1darray): Wave frequency array with shape (nf).
+        - dir (1darray): Wave direction array with shape (nd).
+        - dpt (float): Water depth, deep water approximation used if nan.
+        - scut (float): Wave steepness Hm0 / L cutoff, evaluated at the energy
+          period Tm-1,0, at or above which a partition is classified as wind sea.
+        - tail (bool): If True, account for an f^-5 high-frequency tail beyond
+          the last frequency when evaluating the steepness.
+        - swells (int): Number of swell partitions to compute, all detected if
+          None. The default of 1 merges all detected swells into a single
+          partition.
+        - swell_merge (str): How to reduce more than `swells` detected swells down
+          to `swells` partitions: "sum" adds the spectral energy of the smallest
+          excess swells into the last (smallest) kept partition; "hp01" merges
+          excess swells onto their closest neighbour using the Hanson and Phillips
+          (2001) adjacency criteria. Ignored if `swells` is None. Either way, no
+          swell energy is discarded.
+        - ihmax (int): Number of discrete spectral levels in WW3 Watershed code.
+
+    Returns:
+        - specpart (3darray): Wave spectrum partitions sorted in decreasing order of Hs
+          with shape (np, nf, nd).
+
+    Note:
+        - The smooth spectrum `spectrum_smooth` is used to define the watershed
+          boundaries which are applied to the original spectrum.
+        - Unlike ptm1, ptm2 and hp01, wind sea is identified from the steepness
+          of each topographic partition rather than from a wind speed and
+          direction based wave age criterion, so no wind input is required.
+
+    """
+    # Use smooth spectrum to define morphological boundaries
+    watershed_map = specpart.partition(spectrum_smooth, ihmax)
+    nparts = watershed_map.max()
+    dpt = None if np.isnan(dpt) else dpt
+    ddir = abs(dir[1] - dir[0]) if dir.size > 1 else 1.0
+
+    # Classify each topographic partition as wind sea or swell from its steepness
+    wsea_partition = np.zeros_like(spectrum)
+    swell_partitions = []
+    for ipart in range(nparts):
+        part = np.where(watershed_map == ipart + 1, spectrum, 0.0)  # start at 1
+        E = ddir * part.sum(axis=1)
+        if npstats.steepness(E, freq, dpt, tail) >= scut:
+            wsea_partition += part
+        else:
+            swell_partitions.append(part)
+
+    # Sort swells by Hs
+    if swell_partitions:
+        isort = np.argsort(
+            [-npstats.hs(swell, freq, dir) for swell in swell_partitions]
+        )
+        swell_partitions = list(np.array(swell_partitions)[isort])
+
+    # Dealing with the number of swells
+    if swells is None:
+        # Exclude null swell partitions if the number of output swells is undefined
+        swell_partitions = [swell for swell in swell_partitions if swell.sum() > 0]
+    else:
+        if len(swell_partitions) > swells:
+            if swell_merge == "sum":
+                # Keep the `swells - 1` largest swells individually, sum the
+                # spectral energy of the rest into the last kept partition
+                n_individual = max(swells - 1, 0)
+                kept = list(swell_partitions[:n_individual])
+                excess = swell_partitions[n_individual:]
+                if excess:
+                    kept.append(np.sum(excess, axis=0))
+                swell_partitions = kept
+            elif swell_merge == "hp01":
+                # Merge excess swells onto their closest neighbour using HP01's
+                # own adjacency/saddle/angle criteria instead of a plain sum
+                swell_partitions = combine_partitions_hp01(
+                    partitions=swell_partitions,
+                    freq=freq,
+                    dir=dir,
+                    swells=swells,
+                    combine_extra_swells=True,
+                )
+            else:
+                raise ValueError(
+                    f"swell_merge must be 'sum' or 'hp01', got {swell_merge!r}"
+                )
+        if len(swell_partitions) < swells:
+            # Extend partitions list with null spectra -- either fewer than
+            # `swells` were detected in the first place, or hp01 merging
+            # combined some of them down below the requested count
+            n = swells - len(swell_partitions)
+            for i in range(n):
+                swell_partitions.append(np.zeros_like(spectrum))
+
+    return np.array([wsea_partition] + swell_partitions)
+
+
 def np_ptm2(
     spectrum,
     spectrum_smooth,

{wavespectra-4.7.0 → wavespectra-4.9.0}/wavespectra/specarray.py

@@ -479,13 +479,18 @@ class SpecArray(object):
         return tm02.rename(self._my_name())
 
     def dm(self):
-        """Mean wave direction from the 1st spectral moment Dm."""
+        """Mean wave direction from the 1st spectral moment Dm.
+
+        Defined from the sin and cosine components of the first directional
+        moment integrated over frequency and direction.
+
+        """
         if self.dir is None:
             raise ValueError("Cannot calculate dm from 1d, frequency spectra.")
         moms, momc = self.momd(1)
         dm = np.arctan2(
-            moms.sum(dim=attrs.FREQNAME, skipna=False),
-            momc.sum(dim=attrs.FREQNAME, skipna=False),
+            (moms * self.df).sum(dim=attrs.FREQNAME, skipna=False),
+            (momc * self.df).sum(dim=attrs.FREQNAME, skipna=False),
         )
         dm = (270 - R2D * dm) % 360.0
         dm.attrs.update(self._get_cf_attributes(self._my_name()))

{wavespectra-4.7.0 → wavespectra-4.9.0/wavespectra.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavespectra
-Version: 4.7.0
+Version: 4.9.0
 Summary: Library for ocean wave spectra
 Author-email: Wavespectra Developers <r.guedes@oceanum.science>
 Maintainer-email: Rafael Guedes <r.guedes@oceanum.science>, Tom Durrant <t.durrant@oceanum.science>
@@ -42,6 +42,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
@@ -49,6 +50,7 @@ License-File: AUTHORS.rst
 Requires-Dist: click
 Requires-Dist: dask
 Requires-Dist: matplotlib
+Requires-Dist: numpy
 Requires-Dist: python-dateutil
 Requires-Dist: pyyaml
 Requires-Dist: sortedcontainers

{wavespectra-4.7.0 → wavespectra-4.9.0}/wavespectra.egg-info/requires.txt

@@ -1,6 +1,7 @@
 click
 dask
 matplotlib
+numpy
 python-dateutil
 pyyaml
 sortedcontainers