Give building three subgroups

CHANGELOG.md

@@ -1013,6 +1013,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   Annex IV A.3.3. No number changes: the conformance report, the fiches and
   the tests are identical either side of the refactor.
 
+- `phonometry.building` has three subgroups, by what the acoustician is
+  doing. `building.measurement` is the building that exists: the ISO 16283,
+  10140, 10052, 15186 and 10848 methods, the heavy impact sources, the
+  floor-covering improvement, the reception-plate power, and the ISO 717
+  ratings and ISO 12999 uncertainty that go with them.
+  `building.prediction` is the building that does not exist yet: EN 12354-1
+  to -5 and the panel theory behind them. `building.regulation` is the code
+  it has to satisfy, which is the Spanish CTE DB-HR today and the shape any
+  other country takes tomorrow.
+
+  Five modules lose a word their subgroup now says: `building_prediction` and
+  `detailed_prediction` become `prediction.simplified_model` and
+  `prediction.detailed_model`, which is what EN 12354 calls the two routes it
+  offers for the same calculation, and what the module's own text has always
+  called them;
+  `facade_prediction` is `prediction.facade`, `building_uncertainty` is
+  `measurement.uncertainty` and `spanish_building_code` is
+  `regulation.spain`.
+
+  Nothing moves in the namespace: `from phonometry import building` exports
+  the same 251 names, and the nineteen pre-split module paths keep working
+  until 5.0.
+
 - `phonometry.environmental` is `phonometry.environment`, with three
   subgroups that follow how an environmental study is written: what the source
   emits (`environment.sources`: CNOSSOS road and rail, wind turbines), what the

README.md

@@ -106,7 +106,7 @@ tl = underwater.transmission_loss(...)
 | `speech` | Speech Transmission Index STI/STIPA with signal generator (IEC 60268-16 Ed. 5); Speech Intelligibility Index (ANSI S3.5-1997) with the four band-importance procedures and the standard speech spectra; STOI and ESTOI |
 | `hearing` | Age-related thresholds (ISO 7029) and reference thresholds (ISO 389-7); noise-induced hearing loss with HTLAN (ISO 1999); daily noise exposure LEX,8h with Annex C uncertainty (ISO 9612) |
 | `room` | Swept-sine/MLS/Golay impulse responses (ISO 18233); EDT/T20/T30/C50/C80/Ts (ISO 3382-1/2); open-plan speech metrics (ISO 3382-3); reverberation-room absorption (ISO 354); reverberation-time prediction (Sabine to Arau-Puchades); total absorption of furnished rooms (EN 12354-6); image-source impulse responses and the steady-state field; room-noise criteria NC and RC Mark II (ANSI/ASA S12.2) |
-| `building` | Field airborne, impact and façade insulation with R′w/DnT,w/L′nT,w/D2m,nT,w and C/Ctr/CI (ISO 16283-1/2/3, ISO 717-1/2); laboratory R/Ln (ISO 10140) and survey method (ISO 10052); insulation by intensity (ISO 15186); flanking transmission measurement and prediction (ISO 10848, EN 12354-1/2) and façade/outdoor radiation (EN 12354-3/4); measurement uncertainty (ISO 12999-1); panel transmission theory (mass law, coincidence, double walls, slits and apertures); floor-covering improvement (ISO 16251-1); reception-plate power (EN 15657) and installed structure-borne prediction (EN 12354-5); dynamic stiffness (EN 29052-1) |
+| `building` | Measurement: field airborne, impact and façade insulation with R′w/DnT,w/L′nT,w/D2m,nT,w and C/Ctr/CI (ISO 16283-1/2/3, ISO 717-1/2), laboratory R/Ln (ISO 10140), survey method (ISO 10052), intensity method (ISO 15186), laboratory flanking (ISO 10848), heavy impact sources, floor-covering improvement (ISO 16251-1), reception-plate power (EN 15657) and measurement uncertainty (ISO 12999-1). Prediction: EN 12354-1/2 global and detailed models, façade and outdoor radiation (EN 12354-3/4), installed structure-borne sources (EN 12354-5), panel transmission theory (mass law, coincidence, double walls, slits and apertures), ceiling plenums, masonry cavity walls and resilient layers. Regulation: the Spanish CTE DB-HR |
 | `materials` | Absorption ratings αw with classes (ISO 11654) and uncertainty (ISO 12999-2); impedance-tube absorption, impedance and transmission loss (ISO 10534-1/2, ASTM E2611) plus a virtual FDTD tube; porous and multilayer absorber models (Delany-Bazley, Miki, JCA, TMM with MPP and membranes); slow-sound metamaterial absorbers at critical coupling; scattering and diffusion coefficients (ISO 17497-1/2); Schroeder diffuser design and far-field prediction; deep-subwavelength metadiffusers; in-situ road-surface absorption (ISO 13472-1/2); airflow resistance (ISO 9053-1/2) |
 | `emission` | Sound power by enveloping surface (ISO 3744/3746), reverberation room (ISO 3741), precision anechoic rooms (ISO 3745) and intensity scanning with field indicators and grades (ISO 9614-2/3); two-microphone p-p intensity (IEC 61043, ISO 9614-1); sound power from surface vibration (ISO/TS 7849); noise-emission declarations (ISO 4871) |
 | `environment` | Sources: CNOSSOS-EU road and rail emission, wind-turbine apparent sound power and tonal audibility (IEC 61400-11). Propagation: atmospheric absorption (ISO 9613-1) and the ISO 9613-2 general method with per-term octave breakdown, spherical ground effect and wave-theoretic barriers, refraction ray tracing and the GFPE. Assessment: rating levels, Lden/Ldn and adjustments (ISO 1996-1/2), impulsive-sound prominence (NT ACOU 112) and the Spanish RD 1367/2007 |

README_PYPI.md

@@ -113,7 +113,7 @@ tl = underwater.transmission_loss(...)
 | `speech` | Speech Transmission Index STI/STIPA with signal generator (IEC 60268-16 Ed. 5); Speech Intelligibility Index (ANSI S3.5-1997) with the four band-importance procedures and the standard speech spectra; STOI and ESTOI |
 | `hearing` | Age-related thresholds (ISO 7029) and reference thresholds (ISO 389-7); noise-induced hearing loss with HTLAN (ISO 1999); daily noise exposure LEX,8h with Annex C uncertainty (ISO 9612) |
 | `room` | Swept-sine/MLS/Golay impulse responses (ISO 18233); EDT/T20/T30/C50/C80/Ts (ISO 3382-1/2); open-plan speech metrics (ISO 3382-3); reverberation-room absorption (ISO 354); reverberation-time prediction (Sabine to Arau-Puchades); total absorption of furnished rooms (EN 12354-6); image-source impulse responses and the steady-state field; room-noise criteria NC and RC Mark II (ANSI/ASA S12.2) |
-| `building` | Field airborne, impact and façade insulation with R′w/DnT,w/L′nT,w/D2m,nT,w and C/Ctr/CI (ISO 16283-1/2/3, ISO 717-1/2); laboratory R/Ln (ISO 10140) and survey method (ISO 10052); insulation by intensity (ISO 15186); flanking transmission measurement and prediction (ISO 10848, EN 12354-1/2) and façade/outdoor radiation (EN 12354-3/4); measurement uncertainty (ISO 12999-1); panel transmission theory (mass law, coincidence, double walls, slits and apertures); floor-covering improvement (ISO 16251-1); reception-plate power (EN 15657) and installed structure-borne prediction (EN 12354-5); dynamic stiffness (EN 29052-1) |
+| `building` | Measurement: field airborne, impact and façade insulation with R′w/DnT,w/L′nT,w/D2m,nT,w and C/Ctr/CI (ISO 16283-1/2/3, ISO 717-1/2), laboratory R/Ln (ISO 10140), survey method (ISO 10052), intensity method (ISO 15186), laboratory flanking (ISO 10848), heavy impact sources, floor-covering improvement (ISO 16251-1), reception-plate power (EN 15657) and measurement uncertainty (ISO 12999-1). Prediction: EN 12354-1/2 global and detailed models, façade and outdoor radiation (EN 12354-3/4), installed structure-borne sources (EN 12354-5), panel transmission theory (mass law, coincidence, double walls, slits and apertures), ceiling plenums, masonry cavity walls and resilient layers. Regulation: the Spanish CTE DB-HR |
 | `materials` | Absorption ratings αw with classes (ISO 11654) and uncertainty (ISO 12999-2); impedance-tube absorption, impedance and transmission loss (ISO 10534-1/2, ASTM E2611) plus a virtual FDTD tube; porous and multilayer absorber models (Delany-Bazley, Miki, JCA, TMM with MPP and membranes); slow-sound metamaterial absorbers at critical coupling; scattering and diffusion coefficients (ISO 17497-1/2); Schroeder diffuser design and far-field prediction; deep-subwavelength metadiffusers; in-situ road-surface absorption (ISO 13472-1/2); airflow resistance (ISO 9053-1/2) |
 | `emission` | Sound power by enveloping surface (ISO 3744/3746), reverberation room (ISO 3741), precision anechoic rooms (ISO 3745) and intensity scanning with field indicators and grades (ISO 9614-2/3); two-microphone p-p intensity (IEC 61043, ISO 9614-1); sound power from surface vibration (ISO/TS 7849); noise-emission declarations (ISO 4871) |
 | `environment` | Sources: CNOSSOS-EU road and rail emission, wind-turbine apparent sound power and tonal audibility (IEC 61400-11). Propagation: atmospheric absorption (ISO 9613-1) and the ISO 9613-2 general method with per-term octave breakdown, spherical ground effect and wave-theoretic barriers, refraction ray tracing and the GFPE. Assessment: rating levels, Lden/Ldn and adjustments (ISO 1996-1/2), impulsive-sound prominence (NT ACOU 112) and the Spanish RD 1367/2007 |

docs/ERRATA.md

@@ -261,10 +261,10 @@ which is the check that enforces the rule; see
   (the 2017 Formulae (4) and (5)).
 - **Library behaviour:** unaffected. No code path implements the reduced form:
   the façade model computes $D_{2m,nT}$ from Formula (13)
-  ([`facade_prediction.py`](../src/phonometry/building/facade_prediction.py)),
+  ([`facade.py`](../src/phonometry/building/prediction/facade.py)),
   and the survey method converts with the unreduced
   $D_{2m,n} = D_{2m} + k + 10\log_{10}[A_0 T_0/(0{,}16 V)]$ of ISO 10052 Clause 3.15
-  ([`survey_insulation.py`](../src/phonometry/building/survey_insulation.py)).
+  ([`survey_insulation.py`](../src/phonometry/building/measurement/survey_insulation.py)).
   The two standardization constants that *are* pre-folded elsewhere in the
   library are both correct: $0{,}032$ for the Part 2 impact form and $0{,}32$
   for the Part 1 airborne form $D_{nT} = R' + 10\log_{10}(0{,}16 V/(T_0 S_s))$,
@@ -368,7 +368,7 @@ which is the check that enforces the rule; see
 - **Library behaviour:** `in_situ_total_loss_factor` takes $\sum l_k \alpha_k$
   as an input and `perimeter_absorption_coefficient` implements Formula (C.4);
   the Annex L fixture derives all five sums that way rather than using the
-  printed block, and says so ([`tests/building/test_detailed_prediction.py`](../tests/building/test_detailed_prediction.py)).
+  printed block, and says so ([`tests/building/prediction/test_detailed_model.py`](../tests/building/prediction/test_detailed_model.py)).
 - **Status:** unreported.
 
 ## ISO 12354-1:2017 Table L.3 / ISO 12354-2:2017 Table G.3 (external wall ηint)
@@ -564,7 +564,7 @@ which is the check that enforces the rule; see
 - **Library behaviour:** `weighted_lining_improvement` returns the more
   conservative -10 dB at exactly 1 600 Hz and -5 dB above it, the 2000
   reading, with the ambiguity named in the docstring and pinned in
-  [`tests/building/test_resilient_layers.py`](../tests/building/test_resilient_layers.py).
+  [`tests/building/prediction/test_resilient_layers.py`](../tests/building/prediction/test_resilient_layers.py).
 - **Status:** unreported.
 
 - **Related, not an erratum:** NOTE 1 of the same table sets a floor of 0 dB
@@ -625,7 +625,7 @@ which is the check that enforces the rule; see
   12354-1:2017 prints the same $\pi$-free form in its symbol definitions
   ($f_c = c_0^2/(1{,}8 c_L t)$).
 - **Library behaviour:** implements the $\pi$-free form
-  (`phonometry.building.flanking_transmission.critical_frequency`), with a
+  (`phonometry.building.measurement.flanking_transmission.critical_frequency`), with a
   misprint note in the docstring.
 - **Status:** corrected upstream — ISO 10848-1:2017 (second edition) prints
   the $\pi$-free form in its Formula (5), $f_c = c_0^2/(1{,}8 h c_L)$,
@@ -1896,7 +1896,7 @@ which is the check that enforces the rule; see
 - **Library behaviour:** the regression test uses $\eta = 1{,}5 \cdot 10^{-3}$,
   the value
   the printed answers require
-  ([`tests/building/test_panel_transmission.py`](../tests/building/test_panel_transmission.py)).
+  ([`tests/building/prediction/test_panel_transmission.py`](../tests/building/prediction/test_panel_transmission.py)).
 - **Status:** unreported (textbook rather than a standard).
 
 ---
@@ -1940,14 +1940,14 @@ which is the check that enforces the rule; see
   Eq. (9.19) at all: the two equations the book presents as a pair are
   inconsistent with each other.
 - **Library behaviour:** `plenum_flanking_reduction_index` in
-  [`ceiling_plenum.py`](../src/phonometry/building/ceiling_plenum.py)
+  [`ceiling_plenum.py`](../src/phonometry/building/prediction/ceiling_plenum.py)
   implements the derived $m'_R$ in both the exponent and the denominator, with
   the reading documented at the formula, and rejects a transmission factor
   above unity rather than reporting a negative sound reduction index. Tests pin
   the monotonicity, the $\tau_\text{cl} \le 1$ bound, the convergence to
   Eq. (9.20)
   and the size of the Eq. (9.17) leakage term at a realistic ceiling
-  ([`tests/building/test_ceiling_plenum.py`](../tests/building/test_ceiling_plenum.py)).
+  ([`tests/building/prediction/test_ceiling_plenum.py`](../tests/building/prediction/test_ceiling_plenum.py)).
 - **Status:** unreported (textbook rather than a standard). Mechel's original
   1980 paper, which Vigran reproduces, was not available to check whether the
   misprint originates there.

docs/api-reference.md

@@ -33,7 +33,7 @@ contour = aircraft.noise_contour(path, powers, distances, sel, lmax, x=gx, y=gy)
 | `phonometry.emission` | Sound power (ISO 3740 family), sound intensity, vibration-based power |
 | `phonometry.room` | Room acoustics (ISO 3382), impulse responses, open-plan, room-noise criteria, reverberation prediction, EN 12354-6 |
 | `phonometry.materials` | Absorption (ISO 354/11654), impedance tube, airflow resistance, scattering/diffusion, road absorption, dynamic stiffness |
-| `phonometry.building` | Sound insulation measurement and prediction (EN 12354, ISO 717/16283/10140/15186/10052/10848), structure-borne sound |
+| `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.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) |
@@ -52,10 +52,11 @@ warns and delegates as well.
 
 | Deprecated path | Resolves to | Removed in |
 | :--- | :--- | :--- |
-| `phonometry.insulation` | `phonometry.building.insulation` | 4.0 |
+| `phonometry.insulation` | `phonometry.building.measurement.insulation` | 4.0 |
 | `phonometry.metrology.levels` | `phonometry.signals.levels` | 5.0 |
 | `phonometry.hearing.sti` | `phonometry.speech.sti` | 5.0 |
 | `phonometry.vibration.human_vibration` | `phonometry.vibration.human.exposure` | 5.0 |
+| `phonometry.building.spanish_building_code` | `phonometry.building.regulation.spain` | 5.0 |
 | `phonometry.environmental` | `phonometry.environment` | 5.0 |
 
 | Name | Type | Description (Inputs) | Usage Snippet (Outputs) |

docs/detailed-prediction.md

@@ -405,4 +405,4 @@ printed tables are recorded in [Errata](ERRATA.md).
   result the prediction is checked against.
 - [Dynamic stiffness of resilient materials (EN 29052-1)](dynamic-stiffness.md):
   the $s'$ behind the floating floor's resonance frequency.
-- API reference: [`building.detailed_prediction`](https://jmrplens.github.io/phonometry/reference/api/building/detailed-prediction/).
+- API reference: [`building.prediction.detailed_model`](https://jmrplens.github.io/phonometry/reference/api/building/detailed-model/).

docs/facade-insulation.md

@@ -582,4 +582,4 @@ ISO 16283-3 and EN ISO 717-1 for the prediction).
   radiating side of EN 12354-4.
 - [Theory](theory-rooms-buildings.md): the reference-curve derivation behind
   the weighted single-number ratings.
-- API reference: [`building.facade_prediction`](https://jmrplens.github.io/phonometry/reference/api/building/facade-prediction/) and [`building.insulation`](https://jmrplens.github.io/phonometry/reference/api/building/insulation/).
+- API reference: [`building.prediction.facade`](https://jmrplens.github.io/phonometry/reference/api/building/facade/) and [`building.measurement.insulation`](https://jmrplens.github.io/phonometry/reference/api/building/insulation/).

docs/flanking-lab.md

@@ -413,5 +413,5 @@ laboratory reports.
   reference-curve engines behind $D_{n,f,w}$ and $L_{n,f,w}$.
 - [Room-to-room and open-plan acoustics](open-plan-acoustics.md): the
   open-plan context the ceiling flanking path usually appears in.
-- API reference: [`building.flanking_transmission`](https://jmrplens.github.io/phonometry/reference/api/building/flanking-transmission/)
-  and [`building.ceiling_plenum`](https://jmrplens.github.io/phonometry/reference/api/building/ceiling-plenum/).
+- API reference: [`building.measurement.flanking_transmission`](https://jmrplens.github.io/phonometry/reference/api/building/flanking-transmission/)
+  and [`building.prediction.ceiling_plenum`](https://jmrplens.github.io/phonometry/reference/api/building/ceiling-plenum/).

docs/impact-improvement.md

@@ -254,4 +254,4 @@ not a measurement).
   impact model whose Formula (21) consumes $\Delta L_w$.
 - [Insulation Ratings (ISO 717)](insulation-ratings.md): the reference-curve
   engine behind the weighted improvement.
-- API reference: [`building.floor_covering_improvement`](https://jmrplens.github.io/phonometry/reference/api/building/floor-covering-improvement/).
+- API reference: [`building.measurement.floor_covering_improvement`](https://jmrplens.github.io/phonometry/reference/api/building/floor-covering-improvement/).

docs/insulation-field.md

@@ -460,4 +460,4 @@ ISO 16283 family (ISO 16283-3:2016) has its own page.
   used for the insulation spectra.
 - [Theory](theory-rooms-buildings.md): the reference-curve derivation behind the
   weighted single-number ratings.
-- API reference: [`building.insulation`](https://jmrplens.github.io/phonometry/reference/api/building/insulation/) and [`building.building_uncertainty`](https://jmrplens.github.io/phonometry/reference/api/building/building-uncertainty/).
+- API reference: [`building.measurement.insulation`](https://jmrplens.github.io/phonometry/reference/api/building/insulation/) and [`building.measurement.uncertainty`](https://jmrplens.github.io/phonometry/reference/api/building/uncertainty/).

docs/insulation-intensity.md

@@ -322,4 +322,4 @@ apparent $R'_I$. The single-number ratings reuse ISO 717-1.
   reference-curve engine behind $R_{I,w}$ and $D_{I,n,e,w}$.
 - [Sound Intensity](intensity.md): the two-microphone probe, its field
   indicators and the residual-index qualification behind every scan.
-- API reference: [`building.intensity_insulation`](https://jmrplens.github.io/phonometry/reference/api/building/intensity-insulation/).
+- API reference: [`building.measurement.intensity_insulation`](https://jmrplens.github.io/phonometry/reference/api/building/intensity-insulation/).

docs/insulation-lab.md

@@ -289,4 +289,4 @@ procedures behind them.
   engine behind $R_w$ and $L_{n,w}$.
 - [Sound Power](sound-power.md): the $L_W$ methods that share the
   absorption-area machinery of the receiving room.
-- API reference: [`building.lab_insulation`](https://jmrplens.github.io/phonometry/reference/api/building/lab-insulation/).
+- API reference: [`building.measurement.lab_insulation`](https://jmrplens.github.io/phonometry/reference/api/building/lab-insulation/).