Give psychoacoustics two families

CHANGELOG.md

@@ -1036,6 +1036,26 @@ 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.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
+  time-varying Moore-Glasberg of ISO 532-3 and ECMA-418-2) and the ISO 226
+  equal-loudness contours that put a level in phons.
+  `psychoacoustics.quality` holds what the sound is like
+  once its loudness is known: sharpness, roughness, fluctuation strength,
+  tonality, tone audibility and the annoyance models built on them. The ERB
+  scale stays at the root, because both families measure on it.
+
+  Five modules lose the word the family now says: `loudness_zwicker`,
+  `loudness_moore_glasberg`, `loudness_moore_glasberg_time`, `loudness_ecma`
+  and `loudness_contours` become `loudness.zwicker`, `loudness.moore_glasberg`,
+  `loudness.moore_glasberg_time`, `loudness.ecma` and `loudness.contours`;
+  `psychoacoustic_annoyance` becomes `quality.annoyance`.
+
+  Nothing moves in the namespace: `from phonometry import psychoacoustics`
+  exports the same 60 names, and the thirteen pre-split module paths keep
+  working until 5.0.
+
 - `phonometry.materials` has four families, by what the material does rather
   than by how it is measured. `materials.absorbers` holds everything that
   absorbs and the methods that characterise it: ISO 354 in the reverberation

docs/ERRATA.md

@@ -773,7 +773,7 @@ which is the check that enforces the rule; see
   printed p. 20, 220 dpi (Figure 6 and its 11220 tick).
 - **Library behaviour:** uses the internally consistent 89,1 Hz to
   11 200 Hz range (upper end exclusive per the formulas), with a code note
-  in [`tonality.py`](../src/phonometry/psychoacoustics/tonality.py).
+  in [`tonality.py`](../src/phonometry/psychoacoustics/quality/tonality.py).
 - **Status:** unreported.
 
 ## ECMA-418-1:2024 (3rd edition), Formula (21) (repeated constant term)
@@ -795,7 +795,7 @@ which is the check that enforces the rule; see
   Formula (22) as the consistent control. Render: `plan/ECMA-418-1_3rd_edition_december_2024.pdf`, PDF page 25, printed p. 17, 300 dpi.
 - **Library behaviour:** implements the $C_{L,1}$ reading, which is the only one
   that returns a usable band edge, with a code note in
-  [`tonality.py`](../src/phonometry/psychoacoustics/tonality.py).
+  [`tonality.py`](../src/phonometry/psychoacoustics/quality/tonality.py).
 - **Status:** unreported.
 
 ## ECMA-418-1:2024 (3rd edition), clause 11.3 (unresolved field references)
@@ -834,7 +834,7 @@ which is the check that enforces the rule; see
   reading reproduces the Clause 7 roughness calibration (1 asper) to
   0,9999.
 - **Library behaviour:** implements the flush-to-end reading with a code
-  note in [`roughness_ecma.py`](../src/phonometry/psychoacoustics/roughness_ecma.py).
+  note in [`roughness_ecma.py`](../src/phonometry/psychoacoustics/quality/roughness_ecma.py).
 - **Status:** unreported.
 
 ## ECMA-418-2:2025 (4th edition), clause 9.1.4, Formula (127) (HSA kernel phase)
@@ -952,7 +952,7 @@ which is the check that enforces the rule; see
   printed p. 14, 400 dpi.
 - **Library behaviour:** follows the DIN/sqrt(2) reading (it matches the
   only executable reference), with the choice recorded in
-  [`tone_audibility.py`](../src/phonometry/psychoacoustics/tone_audibility.py).
+  [`tone_audibility.py`](../src/phonometry/psychoacoustics/quality/tone_audibility.py).
 - **Status:** unreported.
 
 ## DIN 45681:2005-03, Anhang I, Tabelle I.6, row "6 FG"
@@ -1382,7 +1382,7 @@ which is the check that enforces the rule; see
 - **Library behaviour:** implements $0{,}76 \cdot 10^{-3}$ with a note at the
   formula;
   the carrier-frequency sweep test would catch a regression to the printed
-  value ([`fluctuation_strength.py`](../src/phonometry/psychoacoustics/fluctuation_strength.py)).
+  value ([`fluctuation_strength.py`](../src/phonometry/psychoacoustics/quality/fluctuation_strength.py)).
 - **Status:** unreported (conference paper rather than a standard).
 
 ## Medwin & Clay, Fundamentals of Acoustical Oceanography (1998), Eq. (3.4.30) (boric-acid coefficient)

docs/advanced-loudness.md

@@ -359,7 +359,7 @@ The Zwicker method (ISO 532-1:2017) is the reference: stationary and time-varyin
 - [Sound Quality Metrics](sound-quality.md): the tonality, roughness and
   fluctuation strength built on the same ECMA-418-2 front-end.
 - [Theory](theory-perception.md): the equations behind the loudness models.
-- API reference: [`psychoacoustics.loudness_moore_glasberg`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-moore-glasberg/), [`psychoacoustics.loudness_moore_glasberg_time`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-moore-glasberg-time/) and [`psychoacoustics.loudness_ecma`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-ecma/).
+- API reference: [`psychoacoustics.loudness.moore_glasberg`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/moore-glasberg/), [`psychoacoustics.loudness.moore_glasberg_time`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/moore-glasberg-time/) and [`psychoacoustics.loudness.ecma`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/ecma/).
 
 ## References
 

docs/api-reference.md

@@ -27,7 +27,7 @@ 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.psychoacoustics` | Loudness (Zwicker, ECMA, Moore-Glasberg), sharpness, tonality, roughness, fluctuation strength, annoyance, tonal audibility |
+| `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 |
@@ -59,6 +59,7 @@ warns and delegates as well.
 | `phonometry.building.spanish_building_code` | `phonometry.building.regulation.spain` | 5.0 |
 | `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 |
 
 | Name | Type | Description (Inputs) | Usage Snippet (Outputs) |
 | :--- | :--- | :--- | :--- |

docs/loudness.md

@@ -274,4 +274,4 @@ hearing threshold.
 - [Psychoacoustic annoyance and fluctuation strength](psychoacoustic-annoyance.md):
   the Zwicker and Fastl model that consumes the percentile loudness $N_5$.
 - [Theory](theory-perception.md): the equations behind the loudness models.
-- API reference: [`psychoacoustics.loudness_zwicker`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-zwicker/) and [`psychoacoustics.loudness_contours`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-contours/).
+- API reference: [`psychoacoustics.loudness.zwicker`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/zwicker/) and [`psychoacoustics.loudness.contours`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/contours/).

docs/tone-prominence.md

@@ -215,7 +215,7 @@ other only as supporting evidence.
 - [Impulsive-sound prominence](impulse-prominence.md): the NT ACOU 112
   counterpart for impulsive (rather than tonal) character.
 - [Theory](theory-perception.md): the critical-band model and criteria derivation.
-- API reference: [`psychoacoustics.tonality`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tonality/).
+- API reference: [`psychoacoustics.quality.tonality`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tonality/).
 
 ## References
 

docs/why-phonometry.md

@@ -128,8 +128,8 @@ sample from the metrology core:
 | IEC 61672-1:2013 Table 5 | `lc_peak()` one-cycle/half-cycle peak responses, class 1 limits | `tests/signals/test_levels.py` |
 | IEC 61260-1:2014 Table 1 | Filter-bank class 1/2 acceptance limits via `verify_filter_class()` | `tests/filters/test_compliance.py` |
 | ISO 7196:1995 Table 2 | G weighting (infrasound) at every nominal response value, 0.25–315 Hz | `tests/filters/test_g_weighting.py` |
-| ISO 226:2023 Table 1 and Annex B | Equal-loudness contours and loudness levels against the Annex B tables, hearing threshold against the Table 1 $T_f$ parameters | `tests/psychoacoustics/test_loudness_contours.py` |
-| ECMA-418-1:2024 | TNR/PR tone prominence: critical bandwidths, proximity spacing and prominence criteria against the worked examples in clauses 10–12 | `tests/psychoacoustics/test_tonality.py` |
+| ISO 226:2023 Table 1 and Annex B | Equal-loudness contours and loudness levels against the Annex B tables, hearing threshold against the Table 1 $T_f$ parameters | `tests/psychoacoustics/loudness/test_contours.py` |
+| ECMA-418-1:2024 | TNR/PR tone prominence: critical bandwidths, proximity spacing and prominence criteria against the worked examples in clauses 10–12 | `tests/psychoacoustics/quality/test_tonality.py` |
 | ISO 1996-1:2016 | `lden()`, `ldn()` and `composite_rating_level()` against hand-computed formula values | `tests/environment/assessment/test_rating.py` |
 | IEC 60942:2017 Table 2 | Calibrator short-term stability limits (frequency-dependent, class 1) in `sensitivity()` | `tests/metrology/test_calibration_validation.py` |
 

llms-full.txt

@@ -334,20 +334,20 @@ The generated API reference, one page per module. Fetch these only when a specif
 - [power/sound-power-intensity](https://jmrplens.github.io/phonometry/reference/api/power/sound-power-intensity/)
 - [power/sound-power-reverberation](https://jmrplens.github.io/phonometry/reference/api/power/sound-power-reverberation/)
 - [power/vibration-sound-power](https://jmrplens.github.io/phonometry/reference/api/power/vibration-sound-power/)
+- [psychoacoustics/annoyance](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/annoyance/)
+- [psychoacoustics/contours](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/contours/)
+- [psychoacoustics/ecma](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/ecma/)
 - [psychoacoustics/erb-scale](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/erb-scale/)
 - [psychoacoustics/fluctuation-strength](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/fluctuation-strength/)
 - [psychoacoustics/fluctuation-strength-ecma](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/fluctuation-strength-ecma/)
-- [psychoacoustics/loudness-contours](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-contours/)
-- [psychoacoustics/loudness-ecma](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-ecma/)
-- [psychoacoustics/loudness-moore-glasberg](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-moore-glasberg/)
-- [psychoacoustics/loudness-moore-glasberg-time](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-moore-glasberg-time/)
-- [psychoacoustics/loudness-zwicker](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-zwicker/)
-- [psychoacoustics/psychoacoustic-annoyance](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/psychoacoustic-annoyance/)
+- [psychoacoustics/moore-glasberg](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/moore-glasberg/)
+- [psychoacoustics/moore-glasberg-time](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/moore-glasberg-time/)
 - [psychoacoustics/roughness-ecma](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/roughness-ecma/)
 - [psychoacoustics/sharpness](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/sharpness/)
 - [psychoacoustics/tonality](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tonality/)
 - [psychoacoustics/tonality-ecma](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tonality-ecma/)
 - [psychoacoustics/tone-audibility](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tone-audibility/)
+- [psychoacoustics/zwicker](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/zwicker/)
 - [rooms/crowd-noise](https://jmrplens.github.io/phonometry/reference/api/rooms/crowd-noise/)
 - [rooms/enclosed-space-absorption](https://jmrplens.github.io/phonometry/reference/api/rooms/enclosed-space-absorption/)
 - [rooms/image-source](https://jmrplens.github.io/phonometry/reference/api/rooms/image-source/)
@@ -1315,7 +1315,7 @@ The Zwicker method (ISO 532-1:2017) is the reference: stationary and time-varyin
 - [Sound Quality Metrics](https://jmrplens.github.io/phonometry/guides/sound-quality/): the tonality, roughness and
   fluctuation strength built on the same ECMA-418-2 front-end.
 - [Theory](https://jmrplens.github.io/phonometry/reference/theory/perception/): the equations behind the loudness models.
-- API reference: [`psychoacoustics.loudness_moore_glasberg`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-moore-glasberg/), [`psychoacoustics.loudness_moore_glasberg_time`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-moore-glasberg-time/) and [`psychoacoustics.loudness_ecma`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-ecma/).
+- API reference: [`psychoacoustics.loudness.moore_glasberg`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/moore-glasberg/), [`psychoacoustics.loudness.moore_glasberg_time`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/moore-glasberg-time/) and [`psychoacoustics.loudness.ecma`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/ecma/).
 
 ## References
 
@@ -2240,7 +2240,7 @@ 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.psychoacoustics` | Loudness (Zwicker, ECMA, Moore-Glasberg), sharpness, tonality, roughness, fluctuation strength, annoyance, tonal audibility |
+| `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 |
@@ -2272,6 +2272,7 @@ warns and delegates as well.
 | `phonometry.building.spanish_building_code` | `phonometry.building.regulation.spain` | 5.0 |
 | `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 |
 
 | Name | Type | Description (Inputs) | Usage Snippet (Outputs) |
 | :--- | :--- | :--- | :--- |
@@ -19351,7 +19352,7 @@ hearing threshold.
 - [Psychoacoustic annoyance and fluctuation strength](https://jmrplens.github.io/phonometry/guides/psychoacoustic-annoyance/):
   the Zwicker and Fastl model that consumes the percentile loudness $N_5$.
 - [Theory](https://jmrplens.github.io/phonometry/reference/theory/perception/): the equations behind the loudness models.
-- API reference: [`psychoacoustics.loudness_zwicker`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-zwicker/) and [`psychoacoustics.loudness_contours`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/loudness-contours/).
+- API reference: [`psychoacoustics.loudness.zwicker`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/zwicker/) and [`psychoacoustics.loudness.contours`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/contours/).
 
 ---
 
@@ -40787,7 +40788,7 @@ other only as supporting evidence.
 - [Impulsive-sound prominence](https://jmrplens.github.io/phonometry/guides/impulse-prominence/): the NT ACOU 112
   counterpart for impulsive (rather than tonal) character.
 - [Theory](https://jmrplens.github.io/phonometry/reference/theory/perception/): the critical-band model and criteria derivation.
-- API reference: [`psychoacoustics.tonality`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tonality/).
+- API reference: [`psychoacoustics.quality.tonality`](https://jmrplens.github.io/phonometry/reference/api/psychoacoustics/tonality/).
 
 ## References
 
@@ -43151,8 +43152,8 @@ sample from the metrology core:
 | IEC 61672-1:2013 Table 5 | `lc_peak()` one-cycle/half-cycle peak responses, class 1 limits | `tests/signals/test_levels.py` |
 | IEC 61260-1:2014 Table 1 | Filter-bank class 1/2 acceptance limits via `verify_filter_class()` | `tests/filters/test_compliance.py` |
 | ISO 7196:1995 Table 2 | G weighting (infrasound) at every nominal response value, 0.25–315 Hz | `tests/filters/test_g_weighting.py` |
-| ISO 226:2023 Table 1 and Annex B | Equal-loudness contours and loudness levels against the Annex B tables, hearing threshold against the Table 1 $T_f$ parameters | `tests/psychoacoustics/test_loudness_contours.py` |
-| ECMA-418-1:2024 | TNR/PR tone prominence: critical bandwidths, proximity spacing and prominence criteria against the worked examples in clauses 10–12 | `tests/psychoacoustics/test_tonality.py` |
+| ISO 226:2023 Table 1 and Annex B | Equal-loudness contours and loudness levels against the Annex B tables, hearing threshold against the Table 1 $T_f$ parameters | `tests/psychoacoustics/loudness/test_contours.py` |
+| ECMA-418-1:2024 | TNR/PR tone prominence: critical bandwidths, proximity spacing and prominence criteria against the worked examples in clauses 10–12 | `tests/psychoacoustics/quality/test_tonality.py` |
 | ISO 1996-1:2016 | `lden()`, `ldn()` and `composite_rating_level()` against hand-computed formula values | `tests/environment/assessment/test_rating.py` |
 | IEC 60942:2017 Table 2 | Calibrator short-term stability limits (frequency-dependent, class 1) in `sensitivity()` | `tests/metrology/test_calibration_validation.py` |