Give underwater three families

CHANGELOG.md

@@ -1036,6 +1036,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   the same 251 names, and the nineteen pre-split module paths keep working
   until 5.0.
 
+- `phonometry.underwater` has three families, along the three questions an
+  underwater problem asks. `underwater.sources` is what makes the sound:
+  ISO 17208 ship radiated noise, shipping traffic, impact pile driving and the
+  wind and thermal noise the sea makes on its own. `underwater.propagation` is
+  how it gets there: closed-form transmission loss, Weston's regimes, the
+  numerical solvers (normal modes, rays, parabolic equation), the seabed it
+  reflects off and the sound speed profile it travels through.
+  `underwater.bioacoustics` is who hears it: marine mammal audiograms and the
+  regulatory auditory weighting and exposure criteria built on them. The
+  ISO 18405 quantities and the sonar equation stay at the root, because all
+  three families are written in their terms.
+
+  Four modules lose a word the family now says: `ocean_ambient_noise`,
+  `marine_mammal_audiograms`, `marine_mammal_weighting` and
+  `numerical_propagation` become `sources.ambient_noise`,
+  `bioacoustics.audiograms`, `bioacoustics.weighting` and
+  `propagation.numerical`. The module that was `underwater.propagation` is
+  `propagation.closed_form`, and the name it vacated is the family package,
+  which exports everything the module did: that path keeps working without a
+  notice, since a package cannot be shadowed by an alias that warns.
+
+  Nothing moves in the namespace: `from phonometry import underwater` exports
+  the same 82 names, and the ten pre-split module paths keep working until 5.0.
+
+- The IEC 61043 intensity-instrument class check is
+  `phonometry.emission.intensity_compliance`, next to the intensity chain it
+  verifies, rather than in `phonometry.metrology`. It was the one section of
+  the API reference that had to reach into a second package to stay coherent,
+  and now no section does. Reading the names from `metrology` still works
+  until 5.0, with the usual notice.
+
 - `phonometry.psychoacoustics` has two families, along the split every text on
   sound quality makes. `psychoacoustics.loudness` holds how loud a sound is:
   the four models (ISO 532-1 Zwicker, ISO 532-2 Moore-Glasberg, the

docs/ERRATA.md

@@ -1085,7 +1085,7 @@ which is the check that enforces the rule; see
   de las bandas de octava") carves out octave-only processors as a special
   case. Both are redundant if every class 2 processor is an octave-band one.
 - **Library behaviour:** implements the EN/IEC reading.
-  [`verify_intensity_class`](../src/phonometry/metrology/intensity_compliance.py)
+  [`verify_intensity_class`](../src/phonometry/emission/intensity_compliance.py)
   treats the full 22-band one-third-octave set as attesting either class, and
   the 7-band octave set (63 Hz to 4 kHz) as a class 2 alternative that never
   attests class 1, with both branches pinned by regression tests
@@ -2067,7 +2067,7 @@ which is the check that enforces the rule; see
   (Eqs. (9.42) to (9.47)), and PDF page 487, printed p. 457, 250 dpi
   (Eqs. (9.54) to (9.57)).
 - **Library behaviour:** `weston_regime_boundaries` in
-  [`weston_regimes.py`](../src/phonometry/underwater/weston_regimes.py)
+  [`propagation/weston_regimes.py`](../src/phonometry/underwater/propagation/weston_regimes.py)
   implements the derivation-consistent $k^2H_e^2H/(9\pi\eta)$, which is also
   what keeps $\theta_\text{eff}$ defined with $H$ everywhere the module
   evaluates Eq. (9.47). The
@@ -2102,7 +2102,7 @@ which is the check that enforces the rule; see
   published weighted TTS onset of the same row
   ($179\ \text{dB} = K + C$ with $K = 178$) is unaffected by the third digit.
 - **Library behaviour:**
-  [`marine_mammal_weighting.py`](../src/phonometry/underwater/marine_mammal_weighting.py)
+  [`bioacoustics/weighting.py`](../src/phonometry/underwater/bioacoustics/weighting.py)
   implements 1,36 and keeps the printed 1,37 available as
   `WeightingParameters.c_db_as_printed`, so an assessment that must reproduce
   the published table verbatim still can. Pinned by
@@ -2171,7 +2171,7 @@ which is the check that enforces the rule; see
   printed p. 570, 250 dpi (the errata's reprinted Table 7, with PCA
   123 / 155 / 138 / 161 and OCA 146 / 170 / 161 / 176).
 - **Library behaviour:** the errata-corrected values are the ones implemented
-  in [`marine_mammal_weighting.py`](../src/phonometry/underwater/marine_mammal_weighting.py),
+  in [`bioacoustics/weighting.py`](../src/phonometry/underwater/bioacoustics/weighting.py),
   pinned by `test_southall_table_7_errata_values_are_implemented`, with the
   +159 dB rule itself checked against the audiogram in
   `test_southall_impulsive_peak_spl_is_threshold_at_f0_plus_159_db` for the

docs/api-reference.md

@@ -26,18 +26,18 @@ contour = aircraft.noise_contour(path, powers, distances, sel, lmax, x=gx, y=gy)
 | :--- | :--- |
 | `phonometry.filters` | Octave and fractional-octave filter banks, frequency weightings and time weighting, parametric EQ, IEC 61260-1 and IEC 61672-1 class verification |
 | `phonometry.signals` | Levels (Leq, LAeq, percentiles), Welch and multitaper spectra, coherence, time-frequency, correlation, envelope, cepstrum, phase, synchronous averaging, test signals |
-| `phonometry.metrology` | Calibration, GUM uncertainty and Monte Carlo, data qualification (stationarity, trends, peak statistics), IEC 61043 intensity class |
+| `phonometry.metrology` | Calibration, GUM uncertainty and Monte Carlo, data qualification (stationarity, trends, peak statistics) |
 | `phonometry.psychoacoustics` | Two families: `loudness` (ISO 532-1 Zwicker, ISO 532-2 and ISO 532-3 Moore-Glasberg, ECMA-418-2, ISO 226 equal-loudness contours) and `quality` (sharpness, roughness, fluctuation strength, tonality, tone audibility, annoyance), plus the ERB scale both measure on |
 | `phonometry.speech` | Speech Transmission Index (IEC 60268-16), Speech Intelligibility Index (ANSI S3.5), STOI and ESTOI |
 | `phonometry.hearing` | Audiometric thresholds (ISO 7029/389-7), noise-induced hearing loss (ISO 1999), occupational exposure (ISO 9612) |
-| `phonometry.emission` | Sound power (ISO 3740 family), sound intensity, vibration-based power |
+| `phonometry.emission` | Sound power (ISO 3740 family), sound intensity and the IEC 61043 instrument class it is measured with, vibration-based power |
 | `phonometry.room` | Room acoustics (ISO 3382), impulse responses, open-plan, room-noise criteria, reverberation prediction, EN 12354-6 |
 | `phonometry.building` | Three subgroups: `measurement` (field, laboratory, survey and intensity methods with their ISO 717 ratings and ISO 12999 uncertainty), `prediction` (EN 12354 global and detailed models, facades, panels, apertures, plenums and resilient layers) and `regulation` (national codes) |
 | `phonometry.materials` | Four families by what the material does: `absorbers` (ISO 354, ISO 11654, ISO 12999-2, impedance tube ISO 10534-2, airflow resistance ISO 9053, porous and multilayer models, Biot, slow-sound metamaterials), `diffusers` (Schroeder design, metadiffusers, scattering and diffusion ISO 17497), `surfaces` (in-situ road absorption ISO 13472) and `resilient` (dynamic stiffness EN 29052-1) |
 | `phonometry.vibration` | Three families: `structural` (mobility ISO 7626, plate junctions, radiation, experimental SEA, transfer stiffness ISO 10846), `human` (ISO 2631/5349/8041 exposure and multiple shocks) and `machinery` (fault frequencies and condition monitoring) |
 | `phonometry.environment` | Three subgroups: `sources` (CNOSSOS road and rail emission, wind-turbine apparent sound power), `propagation` (ISO 9613-1/-2, ground effect and barriers, refraction by ray tracing and the parabolic equation) and `assessment` (ISO 1996-1/-2 rating and measurement, impulsive prominence, RD 1367/2007) |
 | `phonometry.aircraft` | EPNL (ICAO Annex 16), SAE ARP 5534 absorption, airport contours (ECAC Doc 29), rotorcraft (ECAC Doc 32) |
-| `phonometry.underwater` | ISO 18405/17208/18406 levels, propagation and Weston regimes, sound speed, sonar equation and detection range, seabed, ambient and ship-traffic noise, marine-mammal audiograms and regulatory auditory weighting, numerical solvers |
+| `phonometry.underwater` | Three families: `sources` (ISO 17208 ship radiated noise, traffic, pile driving, wind and thermal ambient noise), `propagation` (closed-form and Weston transmission loss, normal modes, rays and the parabolic equation, seabed reflection, sound speed) and `bioacoustics` (marine-mammal audiograms and regulatory auditory weighting), over the ISO 18405 quantities and the sonar equation at the root |
 | `phonometry.electroacoustics` | Distortion (IEC 60268-3 / AES17), transfer function and coherence, radiating piston |
 | `phonometry.noise_control` | Reactive silencers (four-pole method), HVAC duct attenuation, machine-enclosure insertion loss |
 | `phonometry.broadcast` | Programme loudness and true peak (ITU-R BS.1770-5, EBU R 128 with Tech 3341/3342) |
@@ -60,6 +60,8 @@ warns and delegates as well.
 | `phonometry.materials.porous_absorber` | `phonometry.materials.absorbers.porous` | 5.0 |
 | `phonometry.environmental` | `phonometry.environment` | 5.0 |
 | `phonometry.psychoacoustics.loudness_zwicker` | `phonometry.psychoacoustics.loudness.zwicker` | 5.0 |
+| `phonometry.underwater.ocean_ambient_noise` | `phonometry.underwater.sources.ambient_noise` | 5.0 |
+| `phonometry.metrology.intensity_compliance` | `phonometry.emission.intensity_compliance` | 5.0 |
 
 | Name | Type | Description (Inputs) | Usage Snippet (Outputs) |
 | :--- | :--- | :--- | :--- |

docs/atmospheric-refraction.md

@@ -9,7 +9,7 @@ and wind change with height, and this **refracts** sound: rays curve, and over a
 few hundred metres the received level can swing by tens of decibels. This page
 covers `phonometry.environment.propagation.refraction`, the
 refracting-atmosphere counterpart of the ocean solvers in
-[`phonometry.underwater.numerical_propagation`](underwater-solvers.md): a
+[`phonometry.underwater.propagation.numerical`](underwater-solvers.md): a
 **ray model** and a **parabolic-equation (PE)** solver, both clean-room from
 Salomons, *Computational Atmospheric Acoustics* (2001) and Attenborough & Van
 Renterghem, *Predicting Outdoor Sound* 2e (2021, Ch. 11).

docs/underwater-solvers.md

@@ -345,7 +345,7 @@ compute the field.
   Green's-function PE marched over ground impedance instead of a seabed.
 - [2D FDTD wave simulation](fdtd-simulation.md): the time-domain
   alternative behind the SOFAR ducting animation of the propagation guide.
-- API reference: [`underwater.numerical_propagation`](https://jmrplens.github.io/phonometry/reference/api/underwater/numerical-propagation/).
+- API reference: [`underwater.propagation.numerical`](https://jmrplens.github.io/phonometry/reference/api/underwater/numerical/).
 
 ## References
 

llms-full.txt

@@ -376,17 +376,17 @@ The generated API reference, one page per module. Fetch these only when a specif
 - [speech/sii](https://jmrplens.github.io/phonometry/reference/api/speech/sii/)
 - [speech/sti](https://jmrplens.github.io/phonometry/reference/api/speech/sti/)
 - [underwater/acoustics](https://jmrplens.github.io/phonometry/reference/api/underwater/acoustics/)
-- [underwater/marine-mammal-audiograms](https://jmrplens.github.io/phonometry/reference/api/underwater/marine-mammal-audiograms/)
-- [underwater/marine-mammal-weighting](https://jmrplens.github.io/phonometry/reference/api/underwater/marine-mammal-weighting/)
-- [underwater/numerical-propagation](https://jmrplens.github.io/phonometry/reference/api/underwater/numerical-propagation/)
-- [underwater/ocean-ambient-noise](https://jmrplens.github.io/phonometry/reference/api/underwater/ocean-ambient-noise/)
+- [underwater/ambient-noise](https://jmrplens.github.io/phonometry/reference/api/underwater/ambient-noise/)
+- [underwater/audiograms](https://jmrplens.github.io/phonometry/reference/api/underwater/audiograms/)
+- [underwater/closed-form](https://jmrplens.github.io/phonometry/reference/api/underwater/closed-form/)
+- [underwater/numerical](https://jmrplens.github.io/phonometry/reference/api/underwater/numerical/)
 - [underwater/pile-driving-noise](https://jmrplens.github.io/phonometry/reference/api/underwater/pile-driving-noise/)
-- [underwater/propagation](https://jmrplens.github.io/phonometry/reference/api/underwater/propagation/)
 - [underwater/seabed-reflection](https://jmrplens.github.io/phonometry/reference/api/underwater/seabed-reflection/)
 - [underwater/ship-radiated-noise](https://jmrplens.github.io/phonometry/reference/api/underwater/ship-radiated-noise/)
 - [underwater/ship-traffic-noise](https://jmrplens.github.io/phonometry/reference/api/underwater/ship-traffic-noise/)
 - [underwater/sonar-equation](https://jmrplens.github.io/phonometry/reference/api/underwater/sonar-equation/)
 - [underwater/sound-speed](https://jmrplens.github.io/phonometry/reference/api/underwater/sound-speed/)
+- [underwater/weighting](https://jmrplens.github.io/phonometry/reference/api/underwater/weighting/)
 - [underwater/weston-regimes](https://jmrplens.github.io/phonometry/reference/api/underwater/weston-regimes/)
 - [vibration/diagnostics](https://jmrplens.github.io/phonometry/reference/api/vibration/diagnostics/)
 - [vibration/experimental-sea](https://jmrplens.github.io/phonometry/reference/api/vibration/experimental-sea/)
@@ -2239,18 +2239,18 @@ contour = aircraft.noise_contour(path, powers, distances, sel, lmax, x=gx, y=gy)
 | :--- | :--- |
 | `phonometry.filters` | Octave and fractional-octave filter banks, frequency weightings and time weighting, parametric EQ, IEC 61260-1 and IEC 61672-1 class verification |
 | `phonometry.signals` | Levels (Leq, LAeq, percentiles), Welch and multitaper spectra, coherence, time-frequency, correlation, envelope, cepstrum, phase, synchronous averaging, test signals |
-| `phonometry.metrology` | Calibration, GUM uncertainty and Monte Carlo, data qualification (stationarity, trends, peak statistics), IEC 61043 intensity class |
+| `phonometry.metrology` | Calibration, GUM uncertainty and Monte Carlo, data qualification (stationarity, trends, peak statistics) |
 | `phonometry.psychoacoustics` | Two families: `loudness` (ISO 532-1 Zwicker, ISO 532-2 and ISO 532-3 Moore-Glasberg, ECMA-418-2, ISO 226 equal-loudness contours) and `quality` (sharpness, roughness, fluctuation strength, tonality, tone audibility, annoyance), plus the ERB scale both measure on |
 | `phonometry.speech` | Speech Transmission Index (IEC 60268-16), Speech Intelligibility Index (ANSI S3.5), STOI and ESTOI |
 | `phonometry.hearing` | Audiometric thresholds (ISO 7029/389-7), noise-induced hearing loss (ISO 1999), occupational exposure (ISO 9612) |
-| `phonometry.emission` | Sound power (ISO 3740 family), sound intensity, vibration-based power |
+| `phonometry.emission` | Sound power (ISO 3740 family), sound intensity and the IEC 61043 instrument class it is measured with, vibration-based power |
 | `phonometry.room` | Room acoustics (ISO 3382), impulse responses, open-plan, room-noise criteria, reverberation prediction, EN 12354-6 |
 | `phonometry.building` | Three subgroups: `measurement` (field, laboratory, survey and intensity methods with their ISO 717 ratings and ISO 12999 uncertainty), `prediction` (EN 12354 global and detailed models, facades, panels, apertures, plenums and resilient layers) and `regulation` (national codes) |
 | `phonometry.materials` | Four families by what the material does: `absorbers` (ISO 354, ISO 11654, ISO 12999-2, impedance tube ISO 10534-2, airflow resistance ISO 9053, porous and multilayer models, Biot, slow-sound metamaterials), `diffusers` (Schroeder design, metadiffusers, scattering and diffusion ISO 17497), `surfaces` (in-situ road absorption ISO 13472) and `resilient` (dynamic stiffness EN 29052-1) |
 | `phonometry.vibration` | Three families: `structural` (mobility ISO 7626, plate junctions, radiation, experimental SEA, transfer stiffness ISO 10846), `human` (ISO 2631/5349/8041 exposure and multiple shocks) and `machinery` (fault frequencies and condition monitoring) |
 | `phonometry.environment` | Three subgroups: `sources` (CNOSSOS road and rail emission, wind-turbine apparent sound power), `propagation` (ISO 9613-1/-2, ground effect and barriers, refraction by ray tracing and the parabolic equation) and `assessment` (ISO 1996-1/-2 rating and measurement, impulsive prominence, RD 1367/2007) |
 | `phonometry.aircraft` | EPNL (ICAO Annex 16), SAE ARP 5534 absorption, airport contours (ECAC Doc 29), rotorcraft (ECAC Doc 32) |
-| `phonometry.underwater` | ISO 18405/17208/18406 levels, propagation and Weston regimes, sound speed, sonar equation and detection range, seabed, ambient and ship-traffic noise, marine-mammal audiograms and regulatory auditory weighting, numerical solvers |
+| `phonometry.underwater` | Three families: `sources` (ISO 17208 ship radiated noise, traffic, pile driving, wind and thermal ambient noise), `propagation` (closed-form and Weston transmission loss, normal modes, rays and the parabolic equation, seabed reflection, sound speed) and `bioacoustics` (marine-mammal audiograms and regulatory auditory weighting), over the ISO 18405 quantities and the sonar equation at the root |
 | `phonometry.electroacoustics` | Distortion (IEC 60268-3 / AES17), transfer function and coherence, radiating piston |
 | `phonometry.noise_control` | Reactive silencers (four-pole method), HVAC duct attenuation, machine-enclosure insertion loss |
 | `phonometry.broadcast` | Programme loudness and true peak (ITU-R BS.1770-5, EBU R 128 with Tech 3341/3342) |
@@ -2273,6 +2273,8 @@ warns and delegates as well.
 | `phonometry.materials.porous_absorber` | `phonometry.materials.absorbers.porous` | 5.0 |
 | `phonometry.environmental` | `phonometry.environment` | 5.0 |
 | `phonometry.psychoacoustics.loudness_zwicker` | `phonometry.psychoacoustics.loudness.zwicker` | 5.0 |
+| `phonometry.underwater.ocean_ambient_noise` | `phonometry.underwater.sources.ambient_noise` | 5.0 |
+| `phonometry.metrology.intensity_compliance` | `phonometry.emission.intensity_compliance` | 5.0 |
 
 | Name | Type | Description (Inputs) | Usage Snippet (Outputs) |
 | :--- | :--- | :--- | :--- |
@@ -3486,7 +3488,7 @@ and wind change with height, and this **refracts** sound: rays curve, and over a
 few hundred metres the received level can swing by tens of decibels. This page
 covers `phonometry.environment.propagation.refraction`, the
 refracting-atmosphere counterpart of the ocean solvers in
-[`phonometry.underwater.numerical_propagation`](https://jmrplens.github.io/phonometry/guides/underwater-solvers/): a
+[`phonometry.underwater.propagation.numerical`](https://jmrplens.github.io/phonometry/guides/underwater-solvers/): a
 **ray model** and a **parabolic-equation (PE)** solver, both clean-room from
 Salomons, *Computational Atmospheric Acoustics* (2001) and Attenborough & Van
 Renterghem, *Predicting Outdoor Sound* 2e (2021, Ch. 11).
@@ -42318,7 +42320,7 @@ compute the field.
   Green's-function PE marched over ground impedance instead of a seabed.
 - [2D FDTD wave simulation](https://jmrplens.github.io/phonometry/guides/fdtd-simulation/): the time-domain
   alternative behind the SOFAR ducting animation of the propagation guide.
-- API reference: [`underwater.numerical_propagation`](https://jmrplens.github.io/phonometry/reference/api/underwater/numerical-propagation/).
+- API reference: [`underwater.propagation.numerical`](https://jmrplens.github.io/phonometry/reference/api/underwater/numerical/).
 
 ## References