jerlov 0.7.1__tar.gz → 0.7.2__tar.gz

{jerlov-0.7.1/jerlov.egg-info → jerlov-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.1
+Version: 0.7.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -62,7 +62,7 @@ w.a(550), w.b(550), w.c(550)
 The same Jerlov water type has different coefficients in different papers, and
 the differences are not small. Solonenko & Mobley (2015) obtained a and b by
 inverting Kd; Williamson & Hollins (2022) measured them. At 510 nm their
-scattering coefficients differ by up to a factor of 2.6.
+scattering coefficients differ by up to a factor of 3.8, at Jerlov III.
 
 The equations differ too. Both papers use the scattering model of Haltrin
 (1999), but with different constants: Haltrin's Eq. (6) gives a

{jerlov-0.7.1 → jerlov-0.7.2}/README.md

@@ -37,7 +37,7 @@ w.a(550), w.b(550), w.c(550)
 The same Jerlov water type has different coefficients in different papers, and
 the differences are not small. Solonenko & Mobley (2015) obtained a and b by
 inverting Kd; Williamson & Hollins (2022) measured them. At 510 nm their
-scattering coefficients differ by up to a factor of 2.6.
+scattering coefficients differ by up to a factor of 3.8, at Jerlov III.
 
 The equations differ too. Both papers use the scattering model of Haltrin
 (1999), but with different constants: Haltrin's Eq. (6) gives a

{jerlov-0.7.1 → jerlov-0.7.2}/jerlov/__init__.py

@@ -96,4 +96,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"

{jerlov-0.7.1 → jerlov-0.7.2}/jerlov/backscattering.py

@@ -67,7 +67,14 @@ def _amplitude(wavelength_nm, salinity_psu) -> np.ndarray:
             f"salinity_psu must be a finite number, 0 or more, not "
             f"{salinity_psu!r}"
         )
-    return (1.38 * (np.asarray(wavelength_nm, dtype=float) / 500.0) ** -4.32
+    wavelength = np.asarray(wavelength_nm, dtype=float)
+    if not np.all(np.isfinite(wavelength)) or np.any(wavelength <= 0):
+        # Zero gave inf and a negative wavelength NaN, each with nothing but
+        # a NumPy RuntimeWarning.
+        raise ValueError(
+            f"wavelength_nm must be a positive number, not {wavelength_nm!r}"
+        )
+    return (1.38 * (wavelength / 500.0) ** -4.32
             * (1 + 0.3 * salinity / 37.0) * 1e-4)
 
 

{jerlov-0.7.1 → jerlov-0.7.2}/jerlov/scene.py

@@ -195,10 +195,12 @@ class Scene:
                 "the water must carry both a and b; c = a + b drives the path"
             )
         self.water = water
-        self.wavelengths = np.asarray(wavelengths, dtype=float)
+        # Copies, so that changing the caller's arrays afterwards cannot
+        # leave the wavelengths out of step with c, evaluated once below.
+        self.wavelengths = np.array(wavelengths, dtype=float)
         if self.wavelengths.ndim != 1 or self.wavelengths.size == 0:
             raise ValueError("wavelengths must be a non-empty 1-D array")
-        self.downwelling = np.asarray(downwelling, dtype=float)
+        self.downwelling = np.array(downwelling, dtype=float)
         if self.downwelling.shape != self.wavelengths.shape:
             raise ValueError("downwelling must have the same shape as wavelengths")
         if np.any(self.downwelling < 0):

{jerlov-0.7.1 → jerlov-0.7.2}/jerlov/water.py

@@ -240,6 +240,9 @@ class Water:
                 f"(available: {available})"
             )
         query = _as_array(wl)
+        # NaN < lo is False, so a NaN wavelength passed the range check and
+        # came back as NaN, warned about the last sample of the table.
+        _require_number(query, "wavelength")
         lo, hi = self.range_nm
         if np.any(query < lo) or np.any(query > hi):
             raise ValueError(
@@ -591,7 +594,8 @@ def descend(surface_water_type: str, depth_m: float, wavelengths, *,
             f"{deepest:g} m, so there is no type to descend through to "
             f"{depth_m:g} m"
         )
-    query = _as_array(wavelengths)
+    # A copy: it is frozen below, and the caller's array must not be.
+    query = np.array(wavelengths, dtype=float, ndmin=1)
     optical_depth = np.zeros_like(query)
     layers: list[tuple[float, float, str]] = []
     kd: dict[str, np.ndarray] = {}
@@ -723,6 +727,8 @@ def kd_spectrum(kd, wavelength_nm: float, at):
         )
     wavelength_nm = float(wavelength_nm)
     query = _as_array(at)
+    _require_number(wavelength_nm, "wavelength_nm")
+    _require_number(query, "at")
     for value, label in ((wavelength_nm, "wavelength_nm"), (query, "at")):
         if np.any(np.asarray(value) < lo) or np.any(np.asarray(value) > hi):
             raise ValueError(f"{label} outside the model range ({lo:g}-{hi:g} nm)")
@@ -800,6 +806,7 @@ def b_from_c(c, wavelength_nm, *, bw, cw, bound: str = "average"):
     if bound not in ratios:
         raise ValueError(f"bound must be one of {sorted(ratios)}")
     query = _as_array(wavelength_nm)
+    _require_number(query, "wavelength_nm")
     if np.any(query < wl[0]) or np.any(query > wl[-1]):
         raise ValueError(
             f"wavelength outside the measured range ({wl[0]:g}-{wl[-1]:g} nm)"

{jerlov-0.7.1 → jerlov-0.7.2/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.1
+Version: 0.7.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -62,7 +62,7 @@ w.a(550), w.b(550), w.c(550)
 The same Jerlov water type has different coefficients in different papers, and
 the differences are not small. Solonenko & Mobley (2015) obtained a and b by
 inverting Kd; Williamson & Hollins (2022) measured them. At 510 nm their
-scattering coefficients differ by up to a factor of 2.6.
+scattering coefficients differ by up to a factor of 3.8, at Jerlov III.
 
 The equations differ too. Both papers use the scattering model of Haltrin
 (1999), but with different constants: Haltrin's Eq. (6) gives a

{jerlov-0.7.1 → jerlov-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jerlov"
-version = "0.7.1"
+version = "0.7.2"
 description = "Inherent optical properties of Jerlov water types, with provenance"
 readme = "README.md"
 requires-python = ">=3.10"

{jerlov-0.7.1 → jerlov-0.7.2}/tests/test_api.py

@@ -588,3 +588,33 @@ def test_c_warns_once_for_a_wavelength_flagged_in_both_a_and_b():
     assert messages[0].startswith("c for Jerlov 3C")
     assert "a missing at 675 nm" in messages[0]
     assert "b reconstructed at 675 nm" in messages[0]
+
+
+# -- 0.7.2: inputs that slipped through -------------------------------------
+
+@pytest.mark.parametrize("call", [
+    lambda: jerlov.water("III").a(float("nan")),
+    lambda: jerlov.water("III").c([500.0, float("nan")]),
+    lambda: jerlov.water("I", source="jerlov1976").kd(float("nan")),
+    lambda: jerlov.water("III", source="solonenko2015").kd_hydrolight(
+        float("nan")),
+    lambda: jerlov.kd_spectrum(0.06, 490.0, float("nan")),
+    lambda: jerlov.kd_spectrum(0.06, float("nan"), 500.0),
+    lambda: jerlov.b_from_c(0.5, float("nan"), bw=0.002, cw=0.066),
+])
+def test_a_wavelength_that_is_not_a_number_is_refused(call):
+    """NaN < lo is False, so NaN passed the range check, came back as NaN,
+    and warned about the last sample of the table instead."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")         # and no misleading warning
+        with pytest.raises(ValueError, match="NaN"):
+            call()
+
+
+def test_descend_leaves_the_callers_array_alone():
+    wl = np.array([450.0, 550.0])
+    d = jerlov.descend("II", 30.0, wl)
+    assert wl.flags.writeable
+    wl[0] = 999.0
+    assert d.wavelengths[0] == 450.0
+    assert not d.wavelengths.flags.writeable

{jerlov-0.7.1 → jerlov-0.7.2}/tests/test_backscattering.py

@@ -216,3 +216,15 @@ def test_a_salinity_that_is_not_one_is_refused():
             with pytest.raises(ValueError, match="salinity_psu"):
                 call(bad)
     jerlov.pure_water_vsf(120.0, 532.0, 0.0)   # fresh water is fine
+
+
+def test_a_wavelength_that_is_not_one_is_refused():
+    for bad in (0.0, -500.0, float("nan"), float("inf")):
+        for call in (lambda w: jerlov.pure_water_vsf(120.0, w),
+                     lambda w: jerlov.pure_water_backscattering(w),
+                     lambda w: jerlov.pure_water_scattering(w),
+                     lambda w: jerlov.bb_from_vsf(0.0021, 140.0, w)):
+            with warnings.catch_warnings():
+                warnings.simplefilter("error")
+                with pytest.raises(ValueError, match="wavelength_nm"):
+                    call(bad)

{jerlov-0.7.1 → jerlov-0.7.2}/tests/test_quoted_figures.py

@@ -37,7 +37,7 @@ def quiet():
 
 
 def test_scattering_at_510nm_differs_by_the_stated_factor():
-    """README and sources_disagree.py both say 3.8 for Jerlov III."""
+    """sources_disagree.py says 3.8 for Jerlov III."""
     with quiet():
         warnings.simplefilter("ignore")
         measured = float(jerlov.water("III").b(510))
@@ -45,6 +45,30 @@ def test_scattering_at_510nm_differs_by_the_stated_factor():
     assert inverted / measured == pytest.approx(3.8, abs=0.05)
 
 
+@source_tree
+def test_the_readme_states_the_largest_disagreement_at_510nm():
+    """The README said "up to a factor of 2.6" while this test's docstring
+    claimed it said 3.8; nothing read the README, so nothing noticed."""
+    from jerlov.sources import SOURCES
+
+    readme = (ROOT / "README.md").read_text()
+    match = re.search(r"differ by up to a factor of ([\d.]+), at Jerlov (\w+)",
+                      readme)
+    assert match, "the README no longer states the factor at 510 nm"
+    common = set(SOURCES["williamson2022"].water_types) & set(
+        SOURCES["solonenko2015"].water_types)
+    with quiet():
+        warnings.simplefilter("ignore")
+        factors = {}
+        for t in common:
+            one = float(jerlov.water(t).b(510))
+            other = float(jerlov.water(t, source="solonenko2015").b(510))
+            factors[t] = max(one, other) / min(one, other)
+    worst = max(factors, key=factors.get)
+    assert worst == match.group(2)
+    assert factors[worst] == pytest.approx(float(match.group(1)), abs=0.05)
+
+
 def test_the_disagreement_does_not_run_one_way():
     """sources_disagree.py claims Jerlov IB goes the other direction."""
     with quiet():

{jerlov-0.7.1 → jerlov-0.7.2}/tests/test_scene.py

@@ -353,3 +353,11 @@ def test_an_observation_with_no_light_has_a_quiet_repr():
     with warnings.catch_warnings():
         warnings.simplefilter("error")
         assert "veiling undefined" in repr(o)
+
+
+def test_a_scene_does_not_follow_later_changes_to_the_callers_arrays():
+    wl, ed = WL.copy(), np.ones(WL.size)
+    s = Scene(jerlov.water("II"), ed, wl)
+    wl[0], ed[0] = 999.0, -1.0
+    assert s.wavelengths[0] == WL[0]
+    assert s.downwelling[0] == 1.0