jerlov 0.7.0__tar.gz → 0.7.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.0
+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
@@ -333,9 +333,12 @@ python examples/from_one_measurement.py        from an instrument reading
 python examples/synthetic_underwater_images.py appearance at range and depth
 python examples/solar_heating.py               for ocean circulation models
 python examples/what_an_eye_sees.py            any spectral sensitivity
+python examples/light_at_depth.py              light through the depth profile
+python examples/measured_scattering.py         Petzold's measured bb/b
+python examples/what_is_in_the_water.py        absorption without the water
 ```
 
-Five scripts, each aimed at a different reader; `examples/README.md` says
+Eight scripts, each aimed at a different reader; `examples/README.md` says
 which to start with. CI runs all of them on every push, so an example that has
 stopped working is a failed build. Every one ends with the assumptions it
 made.

{jerlov-0.7.0 → 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
@@ -308,9 +308,12 @@ python examples/from_one_measurement.py        from an instrument reading
 python examples/synthetic_underwater_images.py appearance at range and depth
 python examples/solar_heating.py               for ocean circulation models
 python examples/what_an_eye_sees.py            any spectral sensitivity
+python examples/light_at_depth.py              light through the depth profile
+python examples/measured_scattering.py         Petzold's measured bb/b
+python examples/what_is_in_the_water.py        absorption without the water
 ```
 
-Five scripts, each aimed at a different reader; `examples/README.md` says
+Eight scripts, each aimed at a different reader; `examples/README.md` says
 which to start with. CI runs all of them on every push, so an example that has
 stopped working is a failed build. Every one ends with the assumptions it
 made.

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

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

{jerlov-0.7.0 → 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.0 → 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.0 → 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.0 → jerlov-0.7.2/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.0
+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
@@ -333,9 +333,12 @@ python examples/from_one_measurement.py        from an instrument reading
 python examples/synthetic_underwater_images.py appearance at range and depth
 python examples/solar_heating.py               for ocean circulation models
 python examples/what_an_eye_sees.py            any spectral sensitivity
+python examples/light_at_depth.py              light through the depth profile
+python examples/measured_scattering.py         Petzold's measured bb/b
+python examples/what_is_in_the_water.py        absorption without the water
 ```
 
-Five scripts, each aimed at a different reader; `examples/README.md` says
+Eight scripts, each aimed at a different reader; `examples/README.md` says
 which to start with. CI runs all of them on every push, so an example that has
 stopped working is a failed build. Every one ends with the assumptions it
 made.

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

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

{jerlov-0.7.0 → 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.0 → 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.0 → 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():
@@ -263,3 +287,86 @@ def test_DATA_md_section_13_states_where_the_coastal_profiles_end():
     for t, depth in (("3C", 70.5), ("9C", 10.5), ("5C", 20.5), ("7C", 20.5)):
         with pytest.raises(jerlov.MissingQuantityError):
             jerlov.descend(t, depth, 500.0)
+
+
+def test_DATA_md_section_20_on_the_measurements_at_715_nm():
+    """1.004 with no spread for 1C, 3C, 5C; 1.018 for III; 14 to 16 percent
+    above the fit, which is aw there."""
+    import numpy as np
+
+    excess = []
+    for t in ("III", "1C", "3C", "5C"):
+        m = jerlov.measured_points(t, "a")
+        k = int(np.where(m.wavelengths == 715.0)[0][0])
+        if t == "III":
+            assert m.values[k] == pytest.approx(1.018, abs=0.0005)
+        else:
+            assert m.values[k] == 1.004
+            assert m.std_dev[k] < 1e-12
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", jerlov.ProvenanceWarning)
+            fitted = jerlov.water(t).a(715.0)
+        assert fitted == pytest.approx(jerlov.pure_water_absorption(715.0),
+                                       rel=0.01)
+        excess.append(100 * (m.values[k] / fitted - 1))
+    assert 13.5 < min(excess) and max(excess) < 16.0
+
+
+def test_examples_README_figures_for_the_depth_profile():
+    """3C receives 530 times more light at 60 m, I a third less; the 1
+    percent level of I rises from 197 to 133 m (all at 490 nm)."""
+    import math
+
+    def one_kd(t, z):
+        return math.exp(-jerlov.water(t, source="jerlov1976").kd(490.0) * z)
+
+    ratio_3c = jerlov.descend("3C", 60.0, 490.0).transmittance / one_kd("3C", 60.0)
+    ratio_i = jerlov.descend("I", 60.0, 490.0).transmittance / one_kd("I", 60.0)
+    assert round(ratio_3c, -1) == 530
+    assert ratio_i == pytest.approx(2 / 3, abs=0.02)
+
+    def depth_of_one_percent(t, layered):
+        for z in [k / 2 for k in range(1, 401)]:
+            t_z = (jerlov.descend(t, z, 490.0).transmittance if layered
+                   else one_kd(t, z))
+            if t_z <= 0.01:
+                return z
+
+    assert depth_of_one_percent("I", False) == 197.0
+    assert depth_of_one_percent("I", True) == 133.0
+
+
+def test_examples_README_figures_for_absorption_by_the_contents():
+    """Twelve times at 412 nm; pure water 78 to 98 percent at 600 nm."""
+    aw412, aw600 = (jerlov.pure_water_absorption(nm) for nm in (412, 600))
+    ratio = ((jerlov.water("5C").a(412) - aw412)
+             / (jerlov.water("IB").a(412) - aw412))
+    assert round(ratio) == 12
+    shares = [aw600 / jerlov.water(t).a(600)
+              for t in jerlov.get_source("williamson2022").water_types]
+    assert (round(100 * min(shares)), round(100 * max(shares))) == (78, 98)
+
+
+def test_examples_README_figure_for_measured_backscatter_ratios():
+    """measured_scattering.py: contrast at 5 m from 4.0 to 2.6 at 550 nm
+    across the coastal and harbor stations' ratios."""
+    import numpy as np
+
+    wl = np.arange(450.0, 651.0, 50.0)
+    w = jerlov.water("1C")
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", jerlov.ProvenanceWarning)
+        scene = jerlov.Scene.at_depth(
+            w, 10.0, np.interp(wl, *jerlov.d65()), wl,
+            kd=jerlov.water("1C", source="austin1986"))
+    contrasts = []
+    for s in jerlov.PETZOLD_STATIONS:
+        if s.startswith("AUTEC"):
+            continue
+        ratio = jerlov.petzold_scattering(s).backscatter_ratio
+        b_inf = jerlov.veiling_radiance_estimate(
+            w, scene.downwelling, wl, backscatter_ratio=ratio)
+        seen = scene.observe(np.full(wl.size, 0.3), 5.0,
+                             veiling_radiance=b_inf)
+        contrasts.append(seen.contrast(b_inf)[2])
+    assert (round(max(contrasts), 1), round(min(contrasts), 1)) == (4.0, 2.6)

{jerlov-0.7.0 → 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