# Upgrading from 3.3 to 4.0

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/start/upgrading/
Language: en
Alternate: https://docs.jmrp.io/phonometry/es/start/upgrading/index.md
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-09-10
Updated: 2026-11-16T21:36:14Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Upgrade to 4.0: what moved, was renamed or removed and how to find its new spelling, the root trim, split modules and units in parameter names.

---

4.0 is a hard break with no compatibility layer. Almost nothing was deleted:
of the 885 names the root exported in 3.3.0, seventy-eight exist nowhere any more
and the rest simply live at a named address instead of a flat one. So most of the
work is an import sweep, and this page is mostly a map.

Read the first two sections and you can fix the imports. Read the third even
if you are in a hurry, because in four places, one of them only for code
written against 4.0.0rc1, the obvious fix is the wrong one, and three of those
four change a number without raising anything.

## The one rule: imports move down one level

In 3.3.0 the root re-exported the whole library, so `from phonometry import
laeq` worked for almost every name. Today the root exports twenty-five things:
the twenty-one subpackages, the three classes that belong to no single domain
(`Signal`, `ReportMetadata`, `PhonometryWarning`) and `__version__`.

```python
import phonometry

print(len(phonometry.__all__))          # 25
print("laeq" in phonometry.__all__)     # False

from phonometry.signals import laeq     # this is the new spelling
```

Measured across the whole surface, 804 of those 885 root names are published
today by exactly one subpackage, none by two, and none needs a path deeper
than `phonometry.<subpackage>`. Three more are still at the root, where they
always were. So the swap is unambiguous: find the subpackage, import from it.

The attribute form was never removed, which is the smallest possible diff for
code that reached through the root:

```python
from phonometry import filters

print(filters.nominal_frequencies(1).labels)
```

### Finding the new home of a name

Rather than search the reference for each one, ask the installed package:

```python
import importlib
import pkgutil

import phonometry


def whereis(name):
    """Every public module that publishes `name`, shallowest first."""
    found = ["phonometry"] if name in phonometry.__all__ else []
    for attribute in phonometry.__all__:
        package = getattr(phonometry, attribute)
        if not hasattr(package, "__path__"):
            continue
        modules = [package.__name__]
        modules += [m.name for m in pkgutil.walk_packages(package.__path__, package.__name__ + ".")]
        for module_name in modules:
            if any(part.startswith("_") for part in module_name.split(".")):
                continue
            try:
                module = importlib.import_module(module_name)
            except ImportError:
                continue
            if name in getattr(module, "__all__", ()):
                found.append(module_name)
    return sorted(found, key=lambda path: path.count("."))


print(whereis("laeq")[0])                  # phonometry.signals
print(whereis("reverberation_time")[0])    # phonometry.room
print(whereis("sensitivity")[0])           # phonometry.metrology
print(whereis("Signal")[0])                # phonometry
```

It walks the tree in about two seconds. When it returns several paths the
shallowest one is the canonical import: a subpackage re-exports what its own
modules publish, and that shallow path is the one the guides and the tests
use. The four names the root still publishes on its own, `Signal`,
`PhonometryWarning`, `ReportMetadata` and `__version__`, come back as
`phonometry` itself. An empty list means the name is in the last section of
this page.

## Modules that split rather than moved

Five of the thirty modules that changed path did not move to one new address.
They were divided, and a reader who follows only the first half of the split
gets an `ImportError` for the rest. These are worth checking one by one, and
the private renderer package is listed with them because the same thing
happened to it:

| 3.3.0 module | Where its contents are now |
| --- | --- |
| `phonometry.impedance_tube` | `materials.absorbers.impedance_tube` (two-microphone transfer function), `materials.absorbers.four_microphone` (`TransferMatrix`, `transfer_matrix_one_load`, `wave_decomposition`, `face_quantities`, `air_layer_transfer_matrix`), `materials.absorbers.standing_wave`, and `fluids` |
| `phonometry.scattering_diffusion` | `materials.diffusers.reverberation_room_scattering` for the reverberation-room part (`ScatteringResult`, `ScatteringUncertainty`, `BASE_PLATE_BANDS_HZ` and the rest), `materials.diffusers.scattering_diffusion` for the nine free-field names |
| `phonometry.materials.porous_absorber` | `materials.absorbers.porous` for the bulk-material models, `materials.absorbers.layered` for the whole multilayer API (`layered_absorber`, `AirLayer`, `MembraneLayer`, `PerforatedPlateLayer`, `MicroperforatedPlateLayer`, `LayeredAbsorberResult`) |
| `phonometry.metrology.spectra` | `signals.spectra`, plus `signals.multitaper` (`multitaper_psd`) and `signals.windows` (`window_metrics`) |
| `phonometry.compliance` | `filters.compliance` (`FilterComplianceResult`, `class_limits`, `verify_filter_class`), `filters.weighting_compliance` (`verify_weighting_class`, `weighting_class_limits`), `aircraft.measurement_system` (`verify_aircraft_noise_system`) |
| `phonometry._plotting` | `phonometry._plot.<domain>`: the 82 renderers were split per domain, so `plot_airborne_insulation` is in `_plot.building` and `plot_age_threshold` in `_plot.hearing`. Private either way, and `.plot()` on the result is the supported route |

The other twenty-five moved whole, and the resolver above finds them without
reading this table. Each of the first three was reachable by two paths in
3.3.0, the flat one and the one under its package, and both are gone.

## Four where the obvious fix is the wrong one

Everything else on this page announces itself the moment you run it, and the
fix is the one it looks like. These four are not that.

### The impedance-tube helpers took kelvin

`air_density_iso` and `speed_of_sound_iso` documented and consumed their
temperature in **kelvin**. Their successors take degrees Celsius, like the
rest of the library. The names changed, so the import fails and you will
notice, but the argument you carry over is the problem: 293.15 is a
legitimate-looking number in either unit.

```python
from phonometry.materials import speed_of_sound_iso10534

print(round(float(speed_of_sound_iso10534(temperature_c=20.0)), 5))      # 343.28784
print(round(float(speed_of_sound_iso10534(temperature_c=293.15)), 5))    # 477.13003
```

343.29 m/s against 477.13 m/s: a 39 % error, no exception, and every
absorption coefficient computed from it is wrong by a plausible-looking
amount. Convert the value, do not just rename the keyword.

| 3.3.0 | 4.0 |
| --- | --- |
| `impedance_tube.air_density_iso(T_kelvin, p_kPa)` | `materials.air_density_iso10534(temperature_c=T_kelvin - 273.15, static_pressure_kpa=p_kPa)` |
| `impedance_tube.speed_of_sound_iso(T_kelvin)` | `materials.speed_of_sound_iso10534(temperature_c=T_kelvin - 273.15)` |

With the conversion applied both return exactly what they returned in 3.3.0,
bit for bit.

### `GasStream` took kelvin

`noise_control.GasStream` held the inlet temperature of IEC 60534-8-3 as
`inlet_temperature_k` in 4.0.0rc1, in **kelvin**, the way Clause 5 reads it.
In 4.0 the field is `inlet_temperature_c`, in degrees Celsius like every other
temperature the library takes, and the conversion to the absolute temperature
Clause 5 needs happens inside. The keyword fails, so you will notice, but
450.0 is as legitimate a number in one unit as in the other: rename the
keyword and keep the number, and the gas is 273.15 K hotter. Annex A's
example 1 at 450 K puts 91.7 dB(A) at 1 m from the pipe; the same 450 read as
degrees Celsius puts 93.0 dB(A) there, and nothing raises.

| 4.0.0rc1 | 4.0 |
| --- | --- |
| `GasStream(inlet_temperature_k=T_kelvin, ...)` | `GasStream(inlet_temperature_c=T_kelvin - 273.15, ...)` |

### `speed_of_sound` is `speed_of_sound_iso17497`, not `fluids.air()`

The `speed_of_sound(temperature)` of 3.3.0, at the top level and in
`materials.scattering_diffusion`, is the ISO 17497-1 one-liner, and in 4.0 it
is `materials.speed_of_sound_iso17497`: the same formula and the same number,
with the temperature, still in degrees Celsius, written by name. The trap is
the other candidate. `fluids.air()` is where the rest of 4.0 reads the speed of
sound of the air from, so it looks like the new home of a function that
returned one, but it computes humid air by IEC 61094-2 Annex F: at 20 °C it
answers 343.99 m/s where the ISO 17497-1 formula answers 343.20 m/s, and
nothing raises. That is small, and it is not nothing if you are reproducing a
measurement made with the old number.

```python
from phonometry import fluids, materials

print(round(float(materials.speed_of_sound_iso17497(temperature_c=20.0)), 2))    # 343.2
air = fluids.air(temperature_c=20.0, relative_humidity_percent=50.0, static_pressure_pa=101_325.0)
print(round(air.speed_of_sound, 2))                                              # 343.99
```

| 3.3.0 | 4.0 |
| --- | --- |
| `speed_of_sound(T_celsius)` | `materials.speed_of_sound_iso17497(temperature_c=T_celsius)` |

### The `tl` field of an underwater result is `pl`

`transmission_loss` became `propagation_loss`, which the import catches, and
the field inside the result was renamed with it. That one does not raise: a
`PropagationLossResult` has no `.tl`, so the `AttributeError` arrives wherever
you read it, which may be far from the call.

```python
from phonometry.underwater.propagation.closed_form import propagation_loss

result = propagation_loss([1000.0], 1000.0)
print(round(float(result.pl[0]), 5))    # 60.06013, the number .tl used to hold
```

The same rename reaches `underwater.sonar_equation`, whose
`transmission_loss` parameter is now `propagation_loss`.

## The environment moved into a dataclass

Five entry points no longer take the ambient conditions as loose numbers.
Renaming the keyword is not enough there, because the parameter is gone
entirely:

| 3.3.0 | 4.0 |
| --- | --- |
| `airport_noise.event_level(..., temperature=15.0, pressure=101.325)` | `event_level(..., atmosphere=AerodromeAtmosphere(temperature_c=15.0, static_pressure_kpa=101.325))` |
| `airport_noise.noise_contour(...)` | the same, with `AerodromeAtmosphere` |
| `rotorcraft_noise.rotorcraft_event_level(..., temperature=15.0, relative_humidity=70.0)` | `rotorcraft_event_level(..., atmosphere=RotorcraftAtmosphere(temperature_c=15.0, relative_humidity_percent=70.0))` |
| `rotorcraft_noise.rotorcraft_noise_contour(...)` | the same, with `RotorcraftAtmosphere` |
| `outdoor_propagation.predicted_receiver_level(..., humidity=70.0)` | `predicted_receiver_level(..., atmosphere=AtmosphericConditions(relative_humidity_percent=70.0))` |

The other options of these functions went into records too, the per-point
rotorcraft overrides among them, and the next section maps them.

```python
from phonometry.aircraft.airport_noise import AerodromeAtmosphere

atmosphere = AerodromeAtmosphere(temperature_c=15.0, static_pressure_kpa=101.325)
print(atmosphere.temperature_c, atmosphere.static_pressure_kpa)
```

## The longest signatures take their options in records

Ten signatures took more than thirteen parameters each, and in 4.0 the
options that belong together are one record. A 3.3.0 keyword among them is
not renamed but gone, so a call that passes one raises `TypeError`: build the
record the keyword went into and pass that. Every field
of a record is written by name, and a field with a default has the default its
keyword had, so a record carries only what you change. The atmospheres of the
section above are records of the same kind; these are the rest:

| 3.3.0 | 4.0 |
| --- | --- |
| `filter_type=`, `ripple=` and `attenuation=` on `octave_filter` and `OctaveFilterBank`, and `resample=` on `OctaveFilterBank` | `design=filters.FilterDesign(filter_type=..., ripple=..., attenuation=..., resample=...)` |
| `calibration_factor=` and `dbfs=` on `octave_filter` and `OctaveFilterBank` | `calibration=filters.LevelCalibration(factor=..., dbfs=...)` |
| `show=` and `plot_file=` on `octave_filter` and `OctaveFilterBank` | `response_plot=filters.ResponsePlot(show=..., file=...)` |
| `stateful=` and `steady_ic=` on `OctaveFilterBank` | `block_processing=filters.BlockProcessing(stateful=..., steady_ic=...)` |
| `polar=`, `polar_frequency=` and `directivity_index_db=` on `microphone_characteristics` | `directivity=electroacoustics.MicrophoneDirectivity(polar=..., frequency=..., index=...)` |
| `noise_voltage=`, `equivalent_noise_level_db=`, `noise_weighting=` and `noise_spectrum=` on `microphone_characteristics` | `noise=electroacoustics.MicrophoneNoise(voltage_v=..., equivalent_level=..., weighting=..., spectrum=...)`, whose weighting is `"A"` or `"468"`, as the table of one spelling per concept says |
| `max_spl_db=`, `max_spl_thd_percent=` and `distortion=` on `microphone_characteristics` | `overload=electroacoustics.MicrophoneOverload(spl=..., thd_percent=..., distortion=...)` |
| `rated_impedance=`, `minimum_load_impedance=`, `powering=` and `supply_current_ma=` on `microphone_characteristics` | `electrical=electroacoustics.MicrophoneElectrical(rated_impedance_ohm=..., min_load_impedance_ohm=..., powering=..., supply_current_ma=...)` |
| `directivity=` (a `RadiatingPistonResult`), `polar=`, `polar_frequency=` and `directivity_index_db=` on `loudspeaker_characteristics` | `directivity=electroacoustics.LoudspeakerDirectivity(piston=..., polar=..., frequency=..., index=...)` |
| `rated_frequency_range=`, `rated_noise_power=`, `rated_sinusoidal_power=` and `resonance_frequency=` on `loudspeaker_characteristics` | `ratings=electroacoustics.LoudspeakerRatings(frequency_range=..., noise_power=..., sinusoidal_power=..., resonance_frequency=...)` |
| `absorption_area=`, `reverberation_time=`, `volume=`, `mean_absorption_coefficient=` and `room_surface=` on `sound_power_pressure` | `room=emission.RoomEnvironment(...)`, with the same five names |
| `distance`, `source_height` and `receiver_height` by position, and `projected_distance=`, on `predicted_receiver_level` | `environment.PropagationGeometry(distance=..., source_height_m=..., receiver_height_m=..., projected_distance=...)` as the second argument, after the sound power level |
| `ground_source=`, `ground_middle=` and `ground_receiver=` on `predicted_receiver_level` | `ground=environment.GroundFactors(source=..., middle=..., receiver=...)` |
| `directivity_index=` and `d_omega=` on `predicted_receiver_level` | `directivity=environment.DirectivityCorrection(index=..., d_omega=...)` |
| `ground_roll=`, `landing_roll=` and `bank=` on `aircraft.event_level` and `noise_contour` | `segments=aircraft.FlightSegmentState(ground_roll=..., landing_roll=..., bank=...)` |
| `atmospheric_method=` on `rotorcraft_event_level` and `rotorcraft_noise_contour` | the `atmospheric_method` of their `RotorcraftAtmosphere` |
| `receiver_height=`, `ground_elevation=`, `flow_resistivity=`, `terrain=` and `terrain_resolution=` on the same two | `ground=aircraft.RotorcraftGround(receiver_height_m=..., ground_elevation=..., flow_resistivity=..., terrain=..., terrain_resolution=...)` |
| `airspeed=`, `path_angle=`, `heading=` and `bank_angle=` on the same two | `track_state=aircraft.RotorcraftTrackState(airspeed=..., path_angle_deg=..., heading=..., bank_angle_deg=...)` |
| `scaling_factor=` and `triangles=` on the same two | `interpolation=aircraft.FlightConditionInterpolation(scaling_factor=..., triangles=...)` |

`OctaveFilterBank(48000, 3)` reads as it did, because the four arguments
callers write by position kept their places; on `octave_filter` every option
after `limits` is written by name.

```python
import numpy as np

from phonometry import filters

x = np.random.default_rng(0).standard_normal(48_000)
try:
    filters.octave_filter(x, 48_000, calibration_factor=2.0)
except TypeError as error:
    print(type(error).__name__)
# TypeError
result = filters.octave_filter(x, 48_000, calibration=filters.LevelCalibration(factor=2.0))
print(len(result.frequencies))
# 11
```

## The air of a model is one `fluid=`

Twenty-two functions of 3.3.0 took the air they compute in as loose numbers:
a speed of sound and a density, for the visco-thermal models a viscosity, a
Prandtl number, a ratio of specific heats and a static pressure, and for the
thermal correction of ISO 9053-2 a specific heat and a thermal conductivity,
each with a default of its own. In 4.0 these twenty-two take one `fluid=`, a
`fluids.Fluid` that carries every property its model reads, and their loose
keywords are gone, so a call that passed one raises `TypeError`. Other functions
that take a speed of sound or a density, `expansion_chamber` among them, keep
their own keywords. Left out, `fluid=` is
`materials.ABSORBER_AIR`, which holds the defaults 3.3.0 had: 343 m/s,
1.205 kg/m³, 1.84·10⁻⁵ Pa s, a Prandtl number of 0.71, a ratio of specific heats
of 1.4 and 101.325 kPa. A call that never passed the air gives the number it
gave.

| 3.3.0 | 4.0 |
| --- | --- |
| `speed_of_sound=` and `air_density=` on `delany_bazley`, `miki`, `membrane_resonance_frequency`, `mass_law_transmission_loss`, `single_panel_transmission_loss`, `double_wall_transmission_loss`, `mass_spring_mass_resonance`, `ground_effect` and `barrier_insertion_loss` | `fluid=` |
| `speed_of_sound=`, `air_density=` and `viscosity=` on `layered_absorber` and `diffuse_field_absorption`; `air_density=` and `viscosity=` on `perforated_plate_impedance` and `microperforated_plate_impedance` | `fluid=` |
| `speed_of_sound=`, `air_density=`, `viscosity=`, `prandtl_number=`, `heat_capacity_ratio=` and `atmospheric_pressure=` on `johnson_champoux_allard`, `slit_helmholtz_absorber` and `critical_coupling_design`, and the same less `speed_of_sound=` on `helmholtz_resonator_impedance`, `slit_effective_properties` and `rectangular_duct_properties` | `fluid=`, whose `static_pressure_pa` is the pressure, in pascals as before |
| `air_density=` on `atmospheric_parabolic_equation` | `fluid=` |
| `speed_of_sound=`, `air_density=`, `specific_heat_ratio=`, `specific_heat_cp=` and `thermal_conductivity=` on `effective_kappa`, and the same less `specific_heat_ratio=` on `thermal_boundary_layer_thickness` | `fluid=`, with another default, below |

Pass the air you mean as a `Fluid`. `fluids.air()` computes one at a
temperature, a humidity and a pressure, and a `Fluid` built by hand carries the
numbers a book prints. A model that reads a property the fluid does not carry
raises `fluids.FluidPropertyUnavailableError`, naming it.

```python
import numpy as np

from phonometry import fluids, materials

f = np.array([250.0, 1000.0])
print(materials.delany_bazley(f, 20_000.0).characteristic_impedance.round(1))
# [971.5-775.5j 609.6-281.1j]
book_air = fluids.Fluid(
    temperature_c=20.0,
    static_pressure_pa=101_325.0,
    composition={},
    model="the air of the book being reproduced",
    validity="",
    properties={"speed_of_sound": 340.0, "density": 1.21},
)
# delany_bazley(f, 20000.0, speed_of_sound=340.0, air_density=1.21) in 3.3.0
print(materials.delany_bazley(f, 20_000.0, fluid=book_air).characteristic_impedance.round(1))
# [965.3-769.6j 606.1-279.j ]
```

Two of the twenty-two take another air by default. `effective_kappa` and
`thermal_boundary_layer_thickness`, the thermal correction of ISO 9053-2,
defaulted in 3.3.0 to the five values ISO 9053-2 Annex A.3 prints, two of
which are not the air the annex says it uses ([errata register](https://docs.jmrp.io/phonometry/reference/errata/)).
In 4.0 they default to that air, IEC 61094-2 Annex F at the Annex A.3 state of
23 °C, 101.325 kPa and 50 % relative humidity. The correction moves in its
fifth figure, `effective_kappa(0.01, 0.001, 250.0)` is 1.400297 where it was
1.400339, and the printed Annex A.3 results still come out.

## A parameter that names a quantity carries its unit

Everywhere else, the ambient conditions kept their place and gained a suffix.
The rule is that a public parameter naming a dimensional quantity ends in the
unit the caller types, because a number is where a unit is lost and no guard
can catch it by magnitude: 101.325 and 101325 are both legitimate pressures
in this library.

| 3.3.0 | 4.0 |
| --- | --- |
| `temperature=` | `temperature_c=` |
| `pressure=` on `air_attenuation`, `air_attenuation_m` (now `air_power_attenuation_per_m`), `atmospheric_attenuation`, `atmospheric_absorption`, `outdoor_propagation_attenuation`, `sae_band_attenuation` (now `band_attenuation_arp5534`), `impedance_adjustment` and `atmospheric_adjustment`, and on the `event_level` and `noise_contour` methods of `AnpAircraft` and `AnpDatabase`; `static_pressure=` on `meteorological_corrections`, `sound_power_anechoic`, `sound_power_reverberation` and `sound_power_comparison`; the fields `AtmosphericAttenuation.pressure`, `AircraftBandAttenuation.pressure` and `ReportMetadata.pressure`, all in kPa | `static_pressure_kpa=` and `.static_pressure_kpa` |
| `static_pressure=` on `alternating_airflow_resistance`, `barometric_pressure=` on `sound_power_intensity_precision`, `atmospheric_pressure=` on `enclosed_gas_stiffness` and `floating_floor_resonance` | `static_pressure_pa=` |
| `atmospheric_pressure=` on `air_density_iso` (now `air_density_iso10534`) and `air_density_astm` (now `air_density_astm_e2611`) | `static_pressure_kpa=` on `air_density_iso10534` and `air_density_astm_e2611` |
| `atmospheric_pressure=` on `johnson_champoux_allard` and the slow-sound functions | the `fluid=` they take now, which carries its own static pressure |
| `humidity=`, `relative_humidity=` | `relative_humidity_percent=` |
| `diameter=` and its thirteen compounds | `diameter_m=` |
| `angle=`, `angles=`, `bank_angle=`, `path_angle=`, `grazing_angle=`, `launch_angles=` | `_deg=` or `_rad=`, whichever the function reads |
| `runway_gradient=` | `runway_gradient_ratio=` |
| `sound_speed_gradient=` | `sound_speed_gradient_per_s=` |

The pressure of the medium has one name. `static_pressure_kpa` or
`static_pressure_pa` is the absolute pressure of the medium a quantity is
computed in (the air, a gas or sea water), in the unit its clause writes it in; a stream pressure measured
in a duct is a gauge pressure and says so (`static_gauge_pressure_pa`), or is
the `static_pressure_pa` of `velocity_pressure_pa` and `total_pressure`, whose
formulas read it that way. `atmospheric_pressure_pa` is kept only for the
outside atmosphere where the same method measures a stream pressure beside it:
`pipe_transmission_loss`, `DownstreamPipe`, `normal_air_density` and
`gas_density_kg_m3`.

One case is worth naming because it was a trap rather than an inconvenience.
`critical_angle` was a field in radians on one result and a parameter in
degrees on the two functions one screen below it, which is the same word for
two things 57 times apart. It is `critical_angle_rad` on the result and
`critical_angle_deg` on the parameters now.

`transmission_loss=` became `propagation_loss=` only in the underwater sonar
and numerical-propagation results. `ReactiveSilencerResult` and
`SoundReductionResult` still call theirs `transmission_loss=`, correctly:
that is what the standards behind them call it.

The EN 29052-1 functions of `materials` follow the same rule, with the unit
of each quantity at the end of its name:

| 3.3.0 | 4.0 |
| --- | --- |
| `apparent_dynamic_stiffness(resonant_frequency=, total_mass_per_area=)` | `resonant_frequency_hz=`, `total_mass_per_area_kg_m2=` |
| `enclosed_gas_stiffness(thickness=)` | `thickness_m=` |
| `installed_dynamic_stiffness(apparent_stiffness, airflow_resistivity, gas_stiffness=)` | `apparent_stiffness_n_m3`, `airflow_resistivity_kpa_s_m2=` by name only, `gas_stiffness_n_m3=` |
| `natural_frequency(dynamic_stiffness=, mass_per_area=)` | `dynamic_stiffness_n_m3=`, `mass_per_area_kg_m2=` |
| `floating_floor_resonance(resonant_frequency=, total_mass_per_area=, floor_mass_per_area=, airflow_resistivity=, thickness=)` | `resonant_frequency_hz=`, `total_mass_per_area_kg_m2=`, `floor_mass_per_area_kg_m2=`, `airflow_resistivity_kpa_s_m2=`, `thickness_m=` |

The airflow resistivity is the one that earns the keyword. EN 29052-1
thresholds it in kPa·s/m², and every other flow resistivity in the library is
in Pa·s/m², a unit a thousand times smaller, so a Pa·s/m² figure passed by
position landed in the wrong branch of clause 8.2 without a word; it is
written by name now. And below 100 kPa·s/m², `installed_dynamic_stiffness` no
longer reads a missing gas term as zero: 3.3.0 returned $s'_\mathrm{t}$ from
`installed_dynamic_stiffness(20e6, 50.0)`, Formula 6 with its second term
dropped, and 4.0 raises and asks for $s'_\mathrm{a}$.

The ISO 13472-1 functions of `materials` spell the microphone out and give
both heights in metres, and two temperatures say which scale they are on:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `mic_height=` and `source_height=` on every ISO 13472-1 function of `materials` that takes them, and on `plot_insitu_geometry` | `microphone_height_m=`, `source_height_m=` |
| `InsituAbsorptionResult.mic_height` and `.source_height` | `.microphone_height_m` and `.source_height_m` |
| `GasStream.inlet_temperature_k`, in kelvin | `inlet_temperature_c`, in degrees Celsius: convert the number, as the section above shows |
| `RoadEmissionCoefficients.temperature_k`, the CNOSSOS-EU $K_m$ in dB per degree, which read as a temperature in kelvin | `temperature_coefficient_db_per_k`: a coefficient per degree is per kelvin, the same number as per degree Celsius |

Lengths take their unit where a second unit competes for the word. A
thickness is in metres on a layer and in millimetres on the catalogue row it
is read from, a spacing is metres between two microphones or hertz between two
spectral lines, a height is metres above the ground and decibels on a
coincidence plateau, and the aircraft package reads its noise-power-distance
tables in feet and computes in metres:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `thickness=` on `PorousLayer`, `AirLayer`, `PerforatedPlateLayer`, `MicroperforatedPlateLayer`, `PoroelasticLayer`, `TransferMatrix`, `BarrierInsertionLoss` and every function that took one: the Biot, four-microphone, perforated-plate, airflow-resistance, resilient-layer, floor-covering, panel, flanking, structure-borne, SEA and point-mobility functions and the geometry plot helpers; `thickness1=` and `thickness2=` on `junction_transmission`, `junction_wave_parameters`, `right_angle_transmission_coefficient`, `point_connection_coupling_loss_factor`, `JunctionTransmissionResult` and `plot_junction_geometry`; `wall_thickness=`, `lining_thickness=`, `plate_thickness=`, `splitter_thickness=`; `specimen_thickness=` on `plot_dynamic_stiffness_rig` and `sample_thickness=` on `plot_impedance_tube_geometry` | `thickness_m=`, `thickness1_m=`, `thickness2_m=`, `wall_thickness_m=`, `lining_thickness_m=`, `plate_thickness_m=`, `splitter_thickness_m=`, `specimen_thickness_m=`, `sample_thickness_m=` |
| `spacing=` on `sound_intensity` and `IntensityResult`, the IEC 61043 functions and `IntensityInstrumentComplianceResult`, and the impedance-tube functions and `ImpedanceTubeResult` | `spacing_m=` |
| `line_spacing=` on the ISO/PAS 20065 tone functions and `ToneAudibilityResult`; `ZoomFFTResult.bin_spacing` | `line_spacing_hz=`; `.bin_spacing_hz` |
| `height=`, `heights=`, `source_height=`, `receiver_height=`, `barrier_height=`, `max_height=`, `height_step=`, `slit_height=`, `plenum_height=`, `drop_height=` and the other heights in metres, `height_fundamental_frequency(height=)` among them | the same name ending in `_m` |
| `plateau_height=` on `plateau_transmission_loss` and `SoundReductionResult` | `plateau_height_db=` |
| `distance=`, `distances=` and their compounds in `aircraft`: `npd_level`, `npd_curve`, `event_level`, `noise_contour`, `noise_fraction`, `AnpNpdCurves`, `AnpDatabase`, `RotorcraftHemisphere`, `hover_ring_hemisphere`, the rotorcraft propagation functions and their results | `distance_m=`, `distances_m=`, `reference_distance_m=`, `horizontal_distance_m=`, `scaled_distance_m=`, `query_distances_m=`, `table_distances_m` |
| `ReportMetadata(mic_spacing=, thickness=)` | `microphone_spacing_m=`, `thickness_m=` |
| `center=`, `width=` and `wavelength=` on `FDTD2D.add_plane_wave` | `center_m=`, `half_width_m=` (the `1/e` half-width, as `GaussianPulse.half_width_s` is in time) and `wavelength_m=`, beside the widths the engine counts in cells |

Thirteen lengths are written by name now as well, because they carry a default
and the name is the only place the unit shows: `npd_curve(query_distances_m=)`,
`static_airflow_resistance(thickness_m=)`, the `distance_m`, `spacing_m` and
`source_height_m` fields of `RotorcraftHemisphere`, `IntensityResult` and
`RoadEmissionResult`, the `thickness1_m` and `thickness2_m` that
`JunctionTransmissionResult` keeps for its drawing, and the ISO 13472-1
`source_height_m` and `microphone_height_m` of `geometric_spreading_factor`,
`geometric_spreading_factor_angle` and `InSituAbsorptionResult`. The duct
`section` that `duct_path` reads is `{"width_m": a, "height_m": b}`, and
`TABLE_D1_QUANTITIES` names `thickness_m` among the quantities a Table D.1 row
is described by. The catalogue rows keep `thickness_mm`, the unit the catalogue
holds every row in whatever unit its source prints, and
`vertical_directivity(height=1)` keeps its name, because 1 or 2 picks a source
line and is not a length.

A rate, a speed and a phase carry their unit too. An absorption coefficient in
dB/km beside the dimensionless absorption coefficient of a wall, a vehicle speed
in km/h beside a wind speed in m/s and a flight speed in knots, and a phase in
radians on a transfer function beside one in degrees on a calibration record
were each the same word for two things:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `absorption_coefficient` on `PropagationLossResult`, `GaussianBeamResult` and `DetectionRangeResult`, in dB/km | `absorption_db_per_km` |
| `air_absorption_coefficient=` on `sound_power_anechoic` and `meteorological_corrections`, in dB/m | `air_absorption_db_per_m=`, the spelling `CalibrationConditions` uses |
| `AtmosphericAttenuation.attenuation_coefficient`, in dB/m | `.attenuation_db_per_m` |
| `air_attenuation=` on `sabine_reverberation_time`, `eyring_reverberation_time`, `millington_sette_reverberation_time`, `fitzroy_reverberation_time`, `arau_puchades_reverberation_time`, `reverberation_time_models` and `image_source_rir`, and `SoundAbsorptionMeasurement.air_attenuation` | `air_attenuation_per_m` |
| `attenuation=` on `tube_wavenumber` and `two_microphone_impedance`, in Np/m | `attenuation_np_per_m=` |
| `attenuation_source=` and `attenuation_receiving=` on `plenum_flanking_reduction_index` | `attenuation_source_per_m=` and `attenuation_receiving_per_m=` |
| `speed=` on `road_rolling_noise`, `road_propulsion_noise`, `road_vehicle_sound_power`, `aerodynamic_sound_power` and `roughness_to_frequency`; `RoadTraffic.speed`, `RailwayVehicle.speed` and `RoadSurfaceCoefficients.speed_range`; `railway_source_power(minimum_speed=)`, all in km/h | `speed_kmh`, `speed_range_kmh` and `min_speed_kmh=`; `RailwayVehicle` takes `speed_kmh=` by name |
| `reference_speed=` on `event_level`, `noise_contour` and `duration_correction`, and `segment_speed=` on `duration_correction` | `reference_speed_m_s=` and `segment_speed_m_s=` |
| `FlightPathKinematics.airspeed` and `.ground_speed`, in m/s | `.airspeed_m_s` and `.ground_speed_m_s` |
| `ground_speed=` on `linear_sound_speed_profile`, `log_linear_sound_speed_profile`, `ray_curvature_radius` and `shadow_zone_distance`, the speed of sound at the ground | `ground_speed_of_sound=` |
| `RayTraceResult.profile_speeds` | `.profile_speeds_of_sound` |
| `blade_passing_frequency(rotational_speed=)` | `rotational_speed_rpm=` |
| `.phase` on `FrequencyResponseResult`, `CrossSpectralDensityResult`, `PhaseDecompositionResult`, `EnvelopeResult` and `MobilityResult`; `.minimum_phase` and `.excess_phase` on `PhaseDecompositionResult`; `CrossSpectralDensityResult.phase_std`, all in radians | `.phase_rad`, `.min_phase_rad`, `.excess_phase_rad` and `.phase_standard_deviation_rad` |
| `residual_index_from_phase_mismatch(phase_mismatch=)` and `IntensityInstrumentComplianceResult.phase_mismatch()`, in degrees | `phase_mismatch_deg=` and `.phase_mismatch_deg()` |

A name is also one spelling inside a package. Where a word was public both bare
and with its unit in the same package, it now keeps its unit if a second unit
competes for it, as in the first table below, and drops it if the word only
ever had the one, as in the table of "One spelling per concept":

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `RotorcraftHemisphere.azimuth` and `.polar`, `RotorcraftEventResult.azimuth` and `.polar`, in degrees | `.azimuth_deg` and `.polar_deg`, as `hemisphere_source_level` takes them |
| `sae_band_attenuation(path_length=)` (now `band_attenuation_arp5534`) and `AircraftBandAttenuation.path_length` | `path_length_m` |
| `gap=` on `double_wall_transmission_loss`, `mass_spring_mass_resonance` and `plot_double_wall_geometry`, and `SoundReductionResult.gap`, in metres | `gap_m`, beside the `gap_mm` of a joint series |
| `HeavyImpactSourceSpec.tolerance` and `HeavyImpactSourceCheck.tolerance`, in dB | `.tolerance_db` |
| `LoudspeakerCharacteristics.input_voltage` and `loudspeaker_characteristics(input_voltage=)`, `MicrophoneNoise.voltage` | `input_voltage_v` and `voltage_v`, as the induction-loop records spell them |
| `LoudspeakerCharacteristics.rated_frequency_range`, `MicrophoneCharacteristics.reference_frequency` and `microphone_characteristics(reference_frequency=)` | `rated_frequency_range_hz` and `reference_frequency_hz`, as the headphone records spell them |
| `SweptSineDistortionResult.thd`, a ratio | `.thd_ratio`, beside the `thd_percent` of the loudspeaker and microphone records |
| `roughness_to_frequency(wavelengths=)`, in millimetres | `wavelengths_mm=`, beside the `wavelengths_m` of an EN 15610 spectrum |
| `sea_water_sound_speed(salinity=, depth=, latitude=)` | `salinity_psu=`, `depth_m=` and `latitude_deg=`, as `sea_water` and `sea_water_density` take them |
| `depth=` on `metadiffuser_reflection`, `metadiffuser_polar_response`, `metadiffuser_diffusion_spectrum` and `plot_metadiffuser_panel_geometry`, and `MetadiffuserResult.depth`, in metres | `depth_m`, beside the `depth_mm` of a ceiling specimen |
| `DynamicStiffnessResult.resonant_frequency`, `.apparent_stiffness`, `.dynamic_stiffness`, `.gas_stiffness` and `.floor_mass_per_area` | `.resonant_frequency_hz`, `.apparent_stiffness_n_m3`, `.dynamic_stiffness_n_m3`, `.gas_stiffness_n_m3` and `.floor_mass_per_area_kg_m2`, as the EN 29052-1 functions take them beside the MN/m³ the standard prints |
| `johnson_champoux_allard(viscous_length=, thermal_length=)`, in metres | `viscous_length_m=` and `thermal_length_m=`, beside the micrometres of a catalogue row |
| `CorrelationResult.duration` and `correlation_random_error(duration=)`, in seconds | `duration_s`, beside the `duration_hours` of `lex_8h` |
| `LevelCrossingResult.duration` and `PeakStatisticsResult.duration`, in seconds | `.duration_s`, beside the `duration_ms` of an IEC 61672-1 toneburst |
| `RigidMassCalibrationResult.tolerance` and `.deviation`, and `tolerance=` on `seat_transmission` and `mean_of_test_runs`, relative figures | `relative_tolerance` and `relative_deviation` |
| `LabAirborneInsulationResult.absorption` and `LabImpactInsulationResult.absorption`, the area A in m² | `.absorption_area` |
| `HelmholtzResonator(neck_length=, neck_side=, cavity_length=, cavity_side=)`; `lattice_step=` on `slit_helmholtz_absorber`, `helmholtz_resonator_impedance`, `critical_coupling_design`, `plot_slit_absorber_geometry` and `SlitResonatorAbsorberResult`; `critical_coupling_design(cavity_length_bounds=)` and `rectangular_duct_properties(side=)` | the same names ending in `_m` |
| `width=` on `plane_wave_limit`, `rectangular_duct_cut_on`, `elbow_insertion_loss`, `lined_rectangular_duct_attenuation`, `unlined_rectangular_duct_attenuation` and `hydraulic_diameter` | `width_m=`, beside their `height_m=` |
| `width=` on `outdoor_attenuation`, `typical_element_mobility`, `slit_transmission_coefficient`, `slit_resonance_frequencies` and `plot_aperture_geometry`, and `ApertureTransmissionResult.width`, in metres | `width_m`, beside the `height_m` of a facade and the `joint_width_mm` of a joint |
| `AircraftBandAttenuation.coefficient`, in dB/m | `.coefficient_db_per_m`, beside the `coefficient_db_per_100m` of an ARP 866A result |
| `LoudspeakerCharacteristics.rated_impedance`, `.minimum_impedance` and `.impedance_modulus`, and `loudspeaker_characteristics(rated_impedance=)`; `rated_impedance` and `minimum_load_impedance` on `MicrophoneCharacteristics` and `MicrophoneElectrical`, and `microphone_characteristics(rated_impedance=, minimum_load_impedance=)` of 3.3.0, all in ohms | the same names ending in `_ohm`, as the headphone and induction-loop records spell them beside the mechanical impedances of a piston, with a minimum spelled `min_` (`rated_impedance_ohm`, `min_impedance_ohm`, `impedance_modulus_ohm`, `min_load_impedance_ohm`); the microphone pair is given as `microphone_characteristics(..., electrical=MicrophoneElectrical(rated_impedance_ohm=..., min_load_impedance_ohm=...))` |
| `flow_resistivity=` on `ground_effect`, `atmospheric_parabolic_equation`, `delany_bazley`, `miki`, `johnson_champoux_allard` and `decoupling_frequency`, `PorousMediumResult.flow_resistivity`, and `barrier_insertion_loss(ground_flow_resistivity=)`, in Pa s/m² | `flow_resistivity_pa_s_m2` and `ground_flow_resistivity_pa_s_m2`, beside the kPa s/m² of the IEC TS 61400-11-2 ground classes and of EN 29052-1 |

A published constant follows the same rule, and it needs it more, because a
number on its own has nothing but its name to say what it is in: `10.0` is
hertz, decibels or a count. A constant that holds one number ends in its unit,
or in `_DB` when it is in decibels, unless it is a count, a factor or a ratio;
a table whose name says what it holds (bands, speeds, heights) ends in the
unit of that. The constants that the 3.3.0 root exported are in the table of
gone names at the end of this page; these are the rest.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `noise_control.ISO7235_GAS_CONSTANT`, 287 J/(kg K) | `ISO7235_AIR_GAS_CONSTANT_J_KG_K` |
| `noise_control.UNIVERSAL_GAS_CONSTANT`, 8314 J/(kmol K) | `IEC60534_MOLAR_GAS_CONSTANT_J_KMOL_K` |
| `noise_control.AIR_SOUND_SPEED_M_S`, `PIPE_SOUND_SPEED_M_S` | `AIR_SPEED_OF_SOUND_M_S`, `PIPE_SPEED_OF_SOUND_M_S` |
| `environment.ROAD_REFERENCE_SPEED`, `RAILWAY_MINIMUM_SPEED`, `TRAM_MINIMUM_SPEED`, `AERODYNAMIC_THRESHOLD_SPEED`, `AERODYNAMIC_REFERENCE_SPEED`, all in km/h | `ROAD_REFERENCE_SPEED_KMH`, `RAILWAY_MIN_SPEED_KMH`, `TRAM_MIN_SPEED_KMH`, `AERODYNAMIC_THRESHOLD_SPEED_KMH`, `AERODYNAMIC_REFERENCE_SPEED_KMH` |
| `environment.ROAD_REFERENCE_TEMPERATURE` | `ROAD_REFERENCE_TEMPERATURE_C` |
| `environment.ROAD_SOURCE_HEIGHT`, `RAILWAY_SOURCE_HEIGHTS` | `ROAD_SOURCE_HEIGHT_M`, `RAILWAY_SOURCE_HEIGHTS_M` |
| `environment.ROAD_OCTAVE_BANDS`, `RAILWAY_OCTAVE_BANDS`, `RAILWAY_THIRD_OCTAVE_BANDS` | the same names ending in `_HZ` |
| `building.LOW_FREQUENCY_BANDS` | `LOW_FREQUENCY_PROCEDURE_BANDS_HZ`, beside the `environment.LOW_FREQUENCY_BANDS_HZ` of another standard |
| `building.HEAVY_IMPACT_OCTAVE_BANDS`, `TABLE_F1_OCTAVE_BANDS`, `DB_HR_FREQUENCIES` | the same names ending in `_HZ` |
| `building.TAPPING_DROP_HEIGHT`, `TAPPING_HAMMER_RADIUS`, `TAPPING_HAMMER_MASS`, `TAPPING_IMPACT_RATE` | `TAPPING_DROP_HEIGHT_M`, `TAPPING_HAMMER_RADIUS_M`, `TAPPING_HAMMER_MASS_KG`, `TAPPING_IMPACT_RATE_HZ` |
| `building.LOW_FREQUENCY_VOLUME_LIMIT` | `LOW_FREQUENCY_VOLUME_LIMIT_M3` |
| `hearing.AUDIOMETRIC_FREQUENCIES`, `PROTECTOR_OCTAVE_BANDS` | `AUDIOMETRIC_FREQUENCIES_HZ`, `PROTECTOR_OCTAVE_BANDS_HZ` |
| `building.MINIMUM_MULTI_JUNCTION_KIJ`, −5 dB | `MIN_MULTI_JUNCTION_KIJ` |
| `broadcast.DBQPS_REFERENCE`, 0.775 V | `DBQPS_REFERENCE_V` |
| `electroacoustics.CARDIOID_RELATIVE_DIRECTIVITY`, `DEFAULT_STABILITY_MARGIN`, both in dB | the same names ending in `_DB` |
| `environment.REFERENCE_JOINT_DENSITY`, joints per metre | `REFERENCE_JOINT_DENSITY_PER_M` |
| `noise_control.ISO7235_ABSOLUTE_ZERO_OFFSET`, 273 K | `ISO7235_ABSOLUTE_ZERO_OFFSET_K` |
| `psychoacoustics.ERB_C1`, in Hz, and `ERB_C2`, per Hz | `ERB_C1_HZ`, `ERB_C2_PER_HZ` |
| `room.COMMUNICATION_SNR`, `PRIVACY_SNR`, both in dB | the same names ending in `_DB` |
| `vibration.UNCONSTRAINED_BELOW`, the −100 % of ISO 8041-1 | `UNCONSTRAINED_BELOW_PERCENT`, beside `CENTRAL_TOLERANCE_PERCENT` and the rest |

The gas constants show why a constant needs its unit as much as a parameter
does. Two constants of one package shared the words "gas constant" for
287 J/(kg K) and 8314 J/(kmol K), and `fluids` publishes 8.314 J/(mol K) as a
third: three figures 29 and 1000 apart under one name. Each now carries its
whole unit.

A time signal that is one physical quantity is named for it, with its unit,
as `velocity_mm_s` already was on the DIN 4150 and DIN 45669 functions; a
signal in any unit is `x`. This only changes a call that wrote the signal by
name:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `pressure=` on `underwater.sound_pressure_level`, `peak_sound_pressure_level`, `sound_exposure_level`, `pile_strike_metrics`, `single_strike_sel` and `strike_sel_spectrum`, and `PileStrikeResult.pressure` | `pressure_pa` |
| `acceleration=` on `vibration.acceleration_dose`, `spinal_response` and `multiple_shock_assessment` | `acceleration_m_s2=` |
| `force=` on `building.impact_force_exposure_level` and `vibration.injected_power` | `force_n=` |

## Conditions and flags are written by name

An ambient or medium condition or a calibration factor that carries a default,
and every public boolean flag, are keyword-only. The conditions are the
temperature, the humidity and the static pressure, the speed of sound and the
density of the medium, and the three ground factors of ISO 9613-2. The rule exists because the call site is
where the meaning is lost: `air_attenuation(freqs, 20.0, 50.0, 101.325)` is a
temperature, a humidity and a pressure in an order nobody remembers, and
`bank.filter(x, True)` says nothing about which of five flags was thrown. A
choice of method or of band set and a count (`mode`, `method`, `fraction`,
`n`, `seed`) are options, not conditions, and the rule leaves them where they
are.

The failure is loud, which is the point:

```python
import numpy as np

from phonometry.signals import leq

x = np.random.default_rng(1).standard_normal(4800) * 0.01

try:
    leq(x, 48000)
except TypeError as error:
    print(error)      # leq() takes 1 positional argument but 2 were given
```

That call is worth a second look. `leq` never had an `fs`, because an energy
average does not need one, so in 3.3.0 the 48000 silently bound to
`calibration_factor` and the answer came back 93.6 dB high with no complaint.
Now it is a `TypeError`, which is what it always should have been.

```python
print(round(float(leq(x, dbfs=True)), 3))
```

These took a condition or a calibration factor by position until now:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `signals.sound_exposure(x, fs, 8.0, cal)` and `lex_8h(x, fs, 8.0, cal)` | `sound_exposure(x, fs, duration_hours=8.0, calibration_factor=cal)` |
| `psychoacoustics.sharpness_din(x, fs, "free", "din", cal)` | `sharpness_din(x, fs, "free", "din", calibration_factor=cal)` |
| `environment.ground_attenuation(d, hs, hr, bands, gs, gm, gr)` | `ground_attenuation(d, hs, hr, frequencies=bands, ground_source=gs, ground_middle=gm, ground_receiver=gr)`, and `projected_distance=` by name |
| the speed of sound by position on `IntensityInstrumentComplianceResult.phase_mismatch_deg`, `emission.phase_mismatch_from_residual_index`, `residual_index_from_phase_mismatch`, `environment.fresnel_number`, `spherical_reflection_coefficient`, `room.reflection_density`, `materials.reflected_path_delay`, `spot_tube_upper_frequency` and `spot_microphone_spacing_bounds` | `speed_of_sound=` |
| `noise_control.LiquidPipe(d, t, rho, c, rho_air, c_air)` | `LiquidPipe(internal_diameter_m=d, wall_thickness_m=t, density=rho, speed_of_sound=c, air_density=rho_air, air_sound_speed=c_air)` |
| `underwater.FluidSeabed(rho, c, rho_water)` | `FluidSeabed(density=rho, speed_of_sound=c, water_density=rho_water)` |
| `io.Signal(data, fs, cal)` | `io.Signal(data, fs, calibration_factor=cal)`, and `channel_labels`, `provenance` and `source` by name |
| `simulation.FDTD2D(c, dx, ...)` (3.3.0) and `simulation.ElasticFDTD2D(c_p, c_s, dx, rho=..., ...)` (4.0.0rc1) | `FDTD2D(c=c, dx=dx, ...)` and `ElasticFDTD2D(c_p=c_p, c_s=c_s, dx=dx, rho=..., ...)`: every argument by name, as `FDTDRun` and `ElasticRun` take theirs. `FDTD2D(0.01, 343.0, shape=...)`, the speed and the spacing swapped, built an engine with cells 343 m wide and a time step of about four hours |

A parameter whose name carries its unit and that has a default is written by
name too. `noise_signal(fs, 2.0)` reads as two seconds only to someone who
remembers the order, and the `_s` that says so is on the parameter, not on the
call:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `signals.noise_signal(fs, 2.0)`, `speech.stipa_signal(fs, 18.0)` | `noise_signal(fs, duration_s=2.0)`, `stipa_signal(fs, duration_s=18.0)` |
| `underwater.ship_source_spectrum(12.0, 100.0)` | `ship_source_spectrum(12.0, length_m=100.0)` |
| the per-sample duration by position on `hearing.job_based_exposure` | `sample_duration_hours=` |

A frequency axis is written by name as well, wherever it sits beside the values
it labels. Two arrays of one length bind either way round without a complaint,
so a call that swaps them answers on the wrong axis instead of failing; the API
reference itself carried `weighted_rating_extended(freqs, r)` and
`weighted_impact_rating_extended(freqs, ln)` with the frequencies where the
levels go. The values stay positional, in the order they
had, and the axis goes behind the `*`:

```python
import numpy as np

from phonometry import room, signals

frequencies = np.array([63.0, 125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0, 8000.0])
levels = np.array([62.0, 56.0, 50.0, 45.0, 41.0, 38.0, 36.0, 35.0])

print(room.noise_criterion(levels, frequencies=frequencies).rating)
smoothed = signals.fractional_octave_smoothing(levels, frequencies=frequencies, domain="db")
print(smoothed.shape)

try:
    room.noise_criterion(levels, frequencies)
except TypeError as error:
    print(error)      # noise_criterion() takes 1 positional argument but 2 were given
```

The axis is `frequencies`, `frequencies_hz` on the two underwater functions
whose formulas are printed in kHz, and `frequency` where a function evaluates
one frequency or many. An array whose name ends in one of them follows the same
rule: the `tone_frequencies` beside the tone levels of ISO/PAS 20065, or the
`critical_frequencies` beside the vibration reduction indices of ISO 12354-1.
These functions took it by position until now:

- `aircraft`: `hover_ring_hemisphere`, `terrain_screening_adjustment`.
- `building`: `a_weighted_max_impact_level`, `apply_low_frequency_procedure`, `ceiling_attenuation_class`, `equivalent_absorption_length`, `impact_improvement`, `improvement_octave_bands`, `perimeter_absorption_coefficient`, `plate_loss_factor`, `reception_plate_power`, `reciprocity_impact_level`, `resonant_sound_reduction_index`, `structural_reverberation_time`, `structure_borne_power_level`, `tapping_machine_characteristic_power_level`, `tapping_machine_coupling_term`, `total_loss_factor`, `weighted_impact_rating_extended`, `weighted_rating_extended`.
- `electroacoustics`: `loudspeaker_characteristics`, `microphone_characteristics`.
- `emission`: `field_indicators`, `octave_band_levels`, `phase_mismatch_from_residual_index`, `precision_background_correction`, `residual_index_from_phase_mismatch`, `sound_energy_in_situ`, `sound_energy_reverberation`, `sound_power_in_duct`, `sound_power_in_situ`, `sound_power_reverberation`, `velocity_level_from_acceleration`, `verify_intensity_class`.
- `environment`: `assess_tonal_survey`, `spherical_reflection_coefficient`, `tonal_correction`, `wind_turbine_tonality`.
- `hearing`: `hearing_level_to_coupler_spl`.
- `materials`: `diffusion_spectrum`, `equivalent_area_uncertainty`, `measure_sound_absorption`, `one_third_octave_absorption`, `practical_coefficient_uncertainty`, `scattering_coefficient_spectrum`, `sound_absorption_coefficient_uncertainty`.
- `noise_control`: `duct_path`, `room_to_room_transmission`, `splitter_silencer_insertion_loss`.
- `psychoacoustics`: `analyze_spectrum`, `assess_tones`, `combined_tone_level`, `equal_loudness_contours`, `mean_narrowband_level`, `tone_level`.
- `room`: `noise_criterion`, `octave_pair_averages`, `room_criterion`, `room_modal_density`, `room_mode_count`, `single_number_average`.
- `signals`: `fractional_octave_smoothing`, whose `fraction` is written by name now too.
- `underwater`: `monopole_source_level`, `weighted_exposure`.
- `vibration`: `characteristic_phase_deviation`, `convert_frf`, `coupling_loss_factor`, `indirect_transfer_stiffness_result`, `power_injection_clf`, `power_injection_matrix`, `transfer_stiffness_indirect`, `verify_phase_response`, `verify_rigid_mass_calibration`, `verify_weighting`, `weighted_acceleration`.

A positional value that came after the axis stays positional and moves up one
place: `convert_frf(value, f, "mobility", "impedance")` is
`convert_frf(value, "mobility", "impedance", frequency=f)`.

A wavelength axis is written by name in the same way.
`environment.roughness_to_frequency(levels, wavelengths, speed)` is
`roughness_to_frequency(levels, wavelengths_mm=wavelengths, speed_kmh=speed)`:
the levels of the roughness table stay positional, and its wavelengths are
written by name with the speed after them, so the km/h of the speed is on the
line as well. `materials.standing_wave_reflection(swr, x_min1, lam)` and
`standing_wave_normalized_impedance(swr, x_min1, lam)` take the wavelength of
each tone by name, `wavelength=lam`: it is a length of the same shape as the
distance to the first minimum beside it, and the two bind either way round.

A signal function takes the samples and their rate by position, and the
quantity that says what it does to them by name. These took that quantity by
position in 3.3.0, even where it is a choice, as the weighting `name` of
`apply_weighting` is, or a count, as an `order` is. The rate may now be left
out when the samples are a `Signal`, which carries its own:

| 3.3.0 | 4.0 |
| --- | --- |
| `linkwitz_riley(x, fs, 1000.0, 4)` | `filters.linkwitz_riley(x, fs, frequency=1000.0, order=4)`, with the `frequency` that was `freq` |
| `parametric_eq(x, fs, sections)` | `filters.parametric_eq(x, fs, sections=sections)` |
| `zoom_fft(x, fs, 900.0, 1100.0)` | `signals.zoom_fft(x, fs, f_min=900.0, f_max=1100.0)` |
| `lifter(x, fs, 0.002)` | `signals.lifter(x, fs, cutoff=0.002)` |
| `time_synchronous_average(x, fs, 0.05)` | `signals.time_synchronous_average(x, fs, period_s=0.05)`, the period in seconds, as its name now says |
| `resample_signal(x, fs, 32000)` | `signals.resample_signal(x, fs, fs_new=32000)` |
| `harmonic_distortion(x, fs, 1000.0, 2)` | `electroacoustics.harmonic_distortion(x, fs, fundamental=1000.0, order=2)` |
| `difference_frequency_distortion(x, fs, 1000.0, 1200.0)` | `electroacoustics.difference_frequency_distortion(x, fs, f1=1000.0, f2=1200.0)` |
| `modulation_distortion(x, fs, 60.0, 7000.0)` | `electroacoustics.modulation_distortion(x, fs, f_low=60.0, f_high=7000.0)` |
| `swept_sine_distortion(recorded, fs, 20.0, 20000.0, 2.0)` | `electroacoustics.swept_sine_distortion(recorded, fs, f1=20.0, f2=20000.0, duration_s=2.0)` |
| `apply_weighting(x, fs, "Wk")` | `vibration.apply_weighting(x, fs, name="Wk")` |
| `sound_intensity(p1, p2, fs, 0.012)` | `emission.sound_intensity(p1, p2, fs, spacing_m=0.012)` |

```python
import numpy as np

from phonometry import io, signals

fs = 8000
x = io.Signal(np.sin(2 * np.pi * 1000.0 * np.arange(fs) / fs), fs)
try:
    signals.zoom_fft(x, fs, 900.0, 1100.0)
except TypeError as error:
    print(error)      # zoom_fft() takes from 1 to 2 positional arguments but 4 were given
zoom = signals.zoom_fft(x, f_min=900.0, f_max=1100.0)
print(zoom.frequencies[np.argmax(zoom.amplitude)])      # 1000.0
```

A record you build and hand to a function is written by name the same way:
`aircraft.RotorcraftHemisphere(freqs, az, po, levels)` is
`RotorcraftHemisphere(frequencies=freqs, azimuth_deg=az, polar_deg=po,
levels=levels)`, and a positional call raises `TypeError`. A result the
library builds and another function takes whole keeps its fields where they
are, since no caller writes it field by field.

Every record you build and hand to a function takes its fields by name, not
only those with an axis. These took them by position in 3.3.0 or 4.0.0rc1:

- `aircraft`: `Aerodrome`, `AerodynamicCoefficients`, `ApproachStep`, `DepartureStep`, `FlightConditionInterpolation`, `JetEngineCoefficients`, `PerformanceAircraft`, `PropellerEngineCoefficients`, `RotorcraftGround`.
- `broadcast`: `QuasiPeakBallistics`.
- `building`: `ApertureTransmissionResult`, `BandPath`, `FacadeElement`, `FlankingPath`, `HomogeneousElement`, `LowFrequencyProcedure`, `SoundReductionResult`.
- `electroacoustics`: `LoudspeakerDirectivity`, `LoudspeakerRatings`, `MicrophoneDirectivity`, `MicrophoneElectrical`, `MicrophoneNoise`, `MicrophoneOverload`.
- `emission`: `GradeConditions`, `PrecisionFieldIndicators`, `RoomEnvironment`.
- `environment`: `Barrier`, `DirectivityCorrection`, `EffectiveSoundSpeedProfile`, `GroundFactors`, `NoisePhase`, `PropagationGeometry`, `RailwayTrack`, `RailwayVehicle`, `RegulationLimits`, `RoadDeviceRating`, `RoadEmissionCoefficients`, `RoadSurfaceCoefficients`, `RoadTraffic`, `RollingStock`, `SourceEmission`.
- `filters`: `EQSection`, `FilterDesign`, `LevelCalibration`.
- `fluids`: `Fluid`.
- `hearing`: `ExposureResult`, `HMLRatingResult`, `SNRRatingResult`, `Task`.
- `io`: `BroadcastMetadata`, `SignalOrigin`.
- `materials`: `AbsorptionRatingResult`, `AirLayer`, `BiotWavesResult`, `HelmholtzResonator`, `MembraneLayer`, `MetadiffuserWell`, `MicroperforatedPlateLayer`, `PerforatedPlateLayer`, `PoroelasticLayer`, `PorousLayer`, `PorousMediumResult`.
- `metrology`: `Quantity`.
- `noise_control`: `DesignCriterion`, `DownstreamPipe`, `DuctElement`, `Expander`, `GasStream`, `LiquidPipe`, `LiquidStream`, `LiquidTrim`, `RegimeBoundaries`, `RoomToRoomResult`, `SourceRoom`, `ValveTrim`.
- `simulation`: `ContourPhasors`, `CWSource`, `ElasticBoundaries`, `ElasticRecording`, `ExplosionSource`, `ForceSource`, `GaussianPulse`, `Material`, `PlaneWaveSource`, `SignalSource`.
- `underwater`: `BeamFan`, `FluidSeabed`, `RayTraceResult`, `VolumeAbsorption`, `WestonSeabed`.
- `vibration`: `FaultFrequencyResult`, `FaultLine`, `WeightingVerification`, `ZoneBoundaries`.

`noise_control.DuctElement("Elbow", [0, 1, 2], [41, 39, 36])` is
`DuctElement(label="Elbow", attenuation=[0, 1, 2], self_noise=[41, 39, 36])`.
`io.Signal(x, fs)` is the one record that keeps its two first fields by
position: the samples and their rate are the pair every function of the
library takes that way.

## One spelling per concept

The public names had drifted into several spellings of the same quantity, and
4.0 keeps the one the majority already used. The rule for the quantities
counted in the plural is the one most of the API followed: a field or a
parameter that holds an array is `frequencies`, `times`, `distances` or
`levels`, and one that holds a single value is singular. A vectorised argument
that takes either a number or an array keeps its name. An axis carries no
unit in its name, because its unit never changes: `frequencies` are in
hertz, `levels` in decibels and the sample rate is `fs` on every function.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `sound_speed` (control valves, silencer measurement, Weston regimes, ambient noise, `FluidSeabed`, `ShipSourceLevelResult`) | `speed_of_sound` |
| `c=` and `rho=` on `sound_intensity`, `c=` on the two phase-mismatch conversions, `phase_mismatch()` (now `phase_mismatch_deg()`), `absorption_coefficient_uncertainty` and `monopole_source_level` | `speed_of_sound=`, `density=` |
| `speed_of_sound_m_s=` on `thickness_critical_frequency_product` | `speed_of_sound=` |
| `sample_rate` on the FDTD `SignalSource`, `STOIResult` and `impact_force_exposure_level` | `fs` |
| `sponge_width=`, `sponge_sides=`, `sponge_reflection=` and `.sponge_width`/`.sponge_sides` on `FDTD2D` and `ElasticFDTD2D` | `absorbing_layer_cells=`, `absorbing_sides=`, `absorbing_layer_reflection=` and `.absorbing_layer_cells`/`.absorbing_sides`, the words the run records use for the same layer, as `FDTDBoundaries.absorbing_layer_cells` and `ElasticBoundaries.absorbing_layer_cells` do; the default is still 0, no layer |
| `FDTD2D.plot_geometry(probes=)` in metres (4.0.0rc1) | `(ix, iy)` cells, as `FDTDRecording.probes`; each is drawn at the cell centre `FDTDResult.probe_positions` records, and a cell off the grid or inside an obstacle is refused as a run refuses it |
| `freq=` on `linkwitz_riley` and `adaptation_term_kc` | `frequency=` and `frequencies=` |
| `band["freq"]` in the `bands` rows of `FilterComplianceResult`, `WeightingComplianceResult` and `IntensityInstrumentComplianceResult`, and `between_nominals["worst_freq"]` on `WeightingComplianceResult` | `band["frequency"]` and `between_nominals["worst_frequency"]` |
| `.frequency` on the results that carry a frequency axis: `IntensityResult`, `FieldIndicators`, `IntensityInstrumentComplianceResult`, `RoomAcousticsResult`, the five auditorium results, `ImpedanceTubeResult`, `PorousMediumResult`, `LayeredAbsorberResult`, `DiffuseFieldAbsorptionResult`, `BiotWavesResult`, `SlitResonatorAbsorberResult`, `MetadiffuserResult`, `TransferMatrix`, the two valve-noise results, `AircraftBandAttenuation`, `AmbientNoiseResult`, `ShipTrafficSpectrum` | `.frequencies` |
| `.band_centers` on the ISO 717 and ISO 11654 ratings (`WeightedRatingResult`, `ImpactRatingResult`, `ExtendedWeightedRatingResult`, `ExtendedImpactRatingResult`, `AbsorptionRatingResult`), `.centre_frequencies` on `EcmaLoudness`, `EcmaTonality`, `EcmaRoughness`, `EcmaFluctuationStrength` and `MooreGlasbergLoudness`, `.band_frequencies` on `FilterComplianceResult` and `STOIResult`, `.bands_hz` on `RoadDeviceRating` | `.frequencies`, the band axis of every result |
| `frequency=` holding an array: the flanking-transmission functions, `internal_spectrum`, `pipe_transmission_loss`, `expander_noise`, `transfer_matrix_one_load`, `transfer_matrix_two_load`, `TransferMatrix.plot` | `frequencies=` |
| `level=` and `frequency=` holding a band axis: `apply_low_frequency_procedure`, `heavy_impact_octave_levels`, `a_weighted_maximum_impact_level`, `standardized_maximum_impact_level`, `ceiling_attenuation_class`, `plenum_flanking_reduction_index`, `single_number_average`, `octave_pair_averages`, `one_third_octave_absorption`, `power_injection_matrix`, `power_injection_clf`, `valve_hydrodynamic_noise`, `indirect_transfer_stiffness_result`, and `frequency_hz=` on `ship_source_spectrum` | `levels=` and `frequencies=` |
| `frequency_hz=` holding an array on `weighted_exposure` and `ocean_ambient_noise` | `frequencies_hz=`; the unit stays because the formulas they evaluate are printed in kHz |
| `.time` on `ZwickerLoudness`, `EcmaLoudness`, `MooreGlasbergTimeVaryingLoudness`, the ECMA-418-2 tonality, roughness and fluctuation-strength results, `DecayCurve`, `QuasiPeakResult` | `.times` |
| `.level` on `DecayCurve`, `NpdLevelResult`, `NoiseContourResult`, `RotorcraftNoiseContourResult`, `LowFrequencyResult`, `DuctPathStage`, `LateLateralResult`, `TransferStiffnessResult` | `.levels` |
| `.distance` on `NpdLevelResult` and `RotorcraftEventResult` | `.distances_m` |
| `frequencies_hz` on the human-vibration instrument checks (`WeightingVerification`, `PhaseVerification`, `characteristic_phase_deviation`, `verify_phase_response`), `levels_db=` on `operating_standard_deviation` and `subinterval_level` | `frequencies`, `levels` |
| `sound_speeds` on `EffectiveSoundSpeedProfile` and `sound_speeds=` on `normal_modes`, `ray_trace`, `gaussian_beams` and `parabolic_equation` | `speeds_of_sound` |
| `SoundSpeedProfile.sound_speed` and `.depth` | `.speeds_of_sound` and `.depths` |
| `omc_uncertainty=` on `sound_power_pressure` and `sound_energy_pressure`, `sigma_omc=` on `sound_power_anechoic`, `precision_uncertainty`, `sound_power_in_situ` and `sound_energy_in_situ`, `.sigma_omc` on `InSituSoundPowerResult` | `sigma_omc_db` |
| `level=`, `measured_level=`, `operational_level=` on `sti_from_impulse_response`, `stipa`, `sti_adjusted_for_levels` and `STIResult.adjusted_for_levels` | `levels=`, `measured_levels=`, `operational_levels=` |
| `.passed` on `AircraftSystemComplianceResult`, `QuasiPeakDynamicsResult`, `HeavyImpactSourceCheck`, `RigidMassCalibrationResult` | `.passes`, as on every other verifier |
| `microphone_characteristics(noise_weighting="CCIR")` (3.3.0, where the weighting was a free label) and `MicrophoneNoise(weighting="CCIR")` (4.0.0rc1) | `noise=MicrophoneNoise(weighting="468")`, the spelling `weighting_filter` and `weighted_thd` use for the ITU-R BS.468-4 curve. The weighting is `"A"` or `"468"`, and `microphone_characteristics` refuses any other with `ValueError` |
| `atmospheric_pressure_kpa=` on the ISO 9613-1 functions, `atmospheric_absorption`, `outdoor_propagation_attenuation`, `AtmosphericAttenuation`, `AtmosphericConditions`, `sae_band_attenuation` (now `band_attenuation_arp5534`), `AircraftBandAttenuation`, `AerodromeAtmosphere`, `RotorcraftAtmosphere`, `impedance_adjustment`, `atmospheric_adjustment`, the `AnpAircraft` and `AnpDatabase` methods, `air_density_iso10534` and `air_density_astm` (now `air_density_astm_e2611`); `atmospheric_pressure_pa=` on `enclosed_gas_stiffness` and `floating_floor_resonance`; `barometric_pressure_pa=` on `sound_power_intensity_precision`; `absolute_pressure_pa=` on `sea_water_density` | `static_pressure_kpa=` or `static_pressure_pa=`, the same unit |
| `ambient_pressure_pa=` on `normal_air_density` | `atmospheric_pressure_pa=`, the outside atmosphere beside the gauge static pressure of the duct |
| `environmental_ratio_from_absorption(absorption_area_m2=)`, `running_rms_decay_time(integration_time_s=)` and `verify_running_rms_decay(integration_time_s=)` | `absorption_area=` and `integration_time=`, the spelling of the rest of their packages |
| `bending_stress(density_kg_m3=)` | `density=`, the spelling of the rest of `vibration` |
| `confidence=` on `building.insulation_coverage_factor`, `materials.absorption_coverage_factor`, `sound_absorption_coefficient_uncertainty`, `equivalent_area_uncertainty`, `practical_coefficient_uncertainty`, `weighted_coefficient_uncertainty`, `single_number_rating_uncertainty` and `environment.environmental_expanded_uncertainty`, and `UncertainValue.confidence` | `coverage=` and `.coverage`, the coverage probability of the GUM; `confidence` is left to the statistical confidence of an interval, as on `signals.power_spectral_density` |

A `DecayCurve` is read by name, `curve.times` and `curve.levels`, and no
longer unpacks as the pair it replaced. The FDTD solvers keep `c` and `rho`, which name the maps their
equations are written in.

A unit has one spelling too. A duration ends in `_s` or `_hours`, an angle in
`_deg`, a speed in kilometres per hour in `_kmh` and one in knots in `_kt`, a
decay rate in `_db_per_s`; `_seconds`, `_degrees`, `_km_h`, `_knots`, `_db_s`
and an `_h` that means hours appear nowhere in the public API any more.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `vibration.phase_tolerance_degrees` | `vibration.phase_tolerance_deg` |
| `ToneBurstResult.burst_seconds` | `.burst_s` |
| `wind_speed_knots=` on `ocean_ambient_noise` and `wind_noise_spectrum`, and `AmbientNoiseResult.wind_speed_knots` | `wind_speed_kt`, the spelling the aircraft speeds use |
| `speed_knots=` on `ship_source_spectrum`, and `ShipTrafficSpectrum.speed_knots` | `speed_kt` |
| `GasStream.molecular_mass`, in kg/kmol | `GasStream.molar_mass_kg_kmol`, the name the fluids catalogue gives its `molar_mass_kg_mol` per mole |

A word is written whole: `ref` is `reference` in every public name that
abbreviated it. SPL, SEL, SNR and RMS stay as they are, terms of art like
`L_max`.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `levels_ref=`, `background_levels_ref=` and `lw_ref=` on `sound_power_comparison` and `sound_energy_comparison` (3.3.0), and on `sound_power_in_situ` and `sound_energy_in_situ` (4.0.0rc1) | `reference_levels=`, `reference_background_levels=` and `reference_sound_power_levels=`, the last as `high_frequency_sound_power_comparison` spells it |
| `InSituSoundPowerResult.background_correction_ref`, `.sound_power_level_ref` and `.sound_energy_level_ref` | `.reference_background_correction`, and `.sound_power_level_at_reference_conditions` and `.sound_energy_level_at_reference_conditions`: the levels with the Annex C correction (C2, to the reference meteorological conditions), not those of the reference source |
| `metrology.sensitivity(ref_signal=)` | `reference_signal=` |

A standard's designation is in a name only where it tells two things apart,
and then it is written one way: the body joined to its number, first in a
constant or a class and last in a function. Where the module already names
the standard, the designation is gone.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `sae_band_attenuation` | `aircraft.band_attenuation_arp5534`, the document it follows |
| `itu_r_468_weighting` | `electroacoustics.weighting_bs468` |
| `air_density_astm` and `speed_of_sound_astm`, and `plane_wave_frequency_range_astm` (4.0.0rc1) | `materials.air_density_astm_e2611`, `speed_of_sound_astm_e2611` and `plane_wave_frequency_range_astm_e2611`, beside `air_density_iso10534` |
| `noise_control.VDI2081_SPECTRAL_CORRECTION` | `noise_control.SPECTRAL_CORRECTION`: the package has no other spectral correction to tell it from, and its own text cites VDI 2081 Part 2 |
| `building.EN_12354_AIR` | `building.EN12354_AIR` |

An identifier is spelled in American English, and in situ is spelled
`in_situ`. A caller types every name, so `center_frequency` on one function
and `centre_frequency` on the next was a `TypeError` to look up. The values a
caller types are held to it too: a `Literal` choice, a default, the key of a
published table and a string of a published tuple of choices. `catalogue`
keeps its spelling: it is an American variant too, every name writes it the
same way, and it is the file format of your own catalogues. A string a source
prints keeps its print, which is why the CNOSSOS surface below is still
`"optimised brushed down concrete"`. The closed choices of the FDTD engines
and their records are typed `Literal` too, a side, a recorded field, a plane
wave's travel and a force's axis, so a type checker refuses
`free_sides="Top"` before the run; nothing changes at run time.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `materials.insitu_reflection_factor`, `insitu_absorption_from_reflection`, `insitu_absorption_coefficient`, `insitu_absorption_spectrum`, `plot_insitu_geometry` and `InsituAbsorptionResult` | `in_situ_reflection_factor`, `in_situ_absorption_from_reflection`, `in_situ_absorption_coefficient`, `in_situ_absorption_spectrum`, `plot_in_situ_geometry` and `InSituAbsorptionResult`, as the other in-situ names of the library were already spelled |
| `centre_frequency` on `critical_bandwidth`, `tonal_audibility`, `assess_tonal_audibility` and `TonalAssessmentResult` | `center_frequency` |
| `centre=` on `room.filter_bandwidth` and `room.source_directivity_limit` | `center=` |
| `location="centre"` on the infinite plate and beam point mobilities and impedances of `vibration` | `location="center"` |
| `.unfavourable_sum` on `WeightedRatingResult`, `ImpactRatingResult` and `AbsorptionRatingResult` | `.unfavorable_sum` |
| `vibration.storey_fundamental_frequency(storeys)`, `STOREY_FREQUENCY_MIN_STOREYS`, `STOREY_FREQUENCY_NUMERATOR_HZ`, `STOREY_PERIOD_COEFFICIENT_S` | `vibration.story_fundamental_frequency(n_stories)`, `STORY_FREQUENCY_MIN_STORIES`, `STORY_FREQUENCY_NUMERATOR_HZ`, `STORY_PERIOD_COEFFICIENT_S` |
| `storeys=` and the model `"storeys"` on `fundamental_period`, `fundamental_frequency` and `estimate_fundamental_frequency` | `n_stories=` and the model `"stories"` |
| `draught=` on `underwater.monopole_source_level` | `draft_m=`, which says its unit as well |
| `procedure="aeroplane"` on `aircraft.effective_perceived_noise_level` | `procedure="airplane"`, still the default |
| `urbanisation=` on `environment.outdoor_quality_objectives` | `urbanization=` |
| `vapour_pressure_pa` on the IEC 60534-8-4 functions of `noise_control` (`differential_pressure_ratio`, `cavitation_differential`, `jet_strouhal_number`, `stage_conditions`, `last_stage_differential`) and on `LiquidStream` | `vapor_pressure_pa` |
| `"water_vapour_mole_fraction"` in the `composition` of `fluids.air()` | `"water_vapor_mole_fraction"` |
| `building.DB_HR_NORMALISED_SPECTRA`, `environment.NORMALISED_RAILWAY_NOISE_SPECTRUM_DB` and `environment.NORMALISED_TRAFFIC_NOISE_SPECTRUM_DB` | `DB_HR_NORMALIZED_SPECTRA`, `NORMALIZED_RAILWAY_NOISE_SPECTRUM_DB` and `NORMALIZED_TRAFFIC_NOISE_SPECTRUM_DB` |
| `simulation.ALUMINIUM` | `simulation.ALUMINUM` |
| `RoadSurface.OPTIMISED_BRUSHED_DOWN_CONCRETE` | `RoadSurface.OPTIMIZED_BRUSHED_DOWN_CONCRETE`, whose value is still the `"optimised brushed down concrete"` that CNOSSOS-EU Table F-4 prints |

A word has one spelling as well. An acronym is written in capitals inside a
class name, as `EPNLResult` and `STIResult` always were; Ecma, which is the
name the organisation gives itself and not an acronym, is the exception
(`EcmaLoudness`). `mic`, `lab` and `std` are spelled out. A count is
`n_<plural>`, and a limit on one is `min_n_` or `max_n_` (`min_n_records`,
`max_n_arrivals`); a duration names its quantity before its unit, never the
unit alone (`exposure_duration_years`, `duration_s`, `period_hours`), with
the minute spelled out (`assessment_period_minutes`) because a trailing `_min`
is a minimum, and a class number, an axis, a number of decimals and a length counted in samples
are not counts. `minimum`
and `maximum` are written `min` and `max` in every public name, `MIN` and `MAX`
in a constant and `Min` and `Max` in a class, as numpy, SciPy, scikit-learn and
Matplotlib write them, terms of art included: the maximum and minimum levels
Lmax and Lmin are `max_level` and `min_level` (never a bare `max_db`), the
takt maximum of DIN 45669-1 and DIN 4150-2 is `TAKT_MAX_FACTOR` and the
minimum-phase reconstruction is `min_phase`. A confidence bound is
`confidence_lower` or `confidence_upper`. A function that reads a time
signal takes it first, as `x`, the name `octave_filter(x, fs)` and the rest
of the signal functions always used; called by position, nothing changes. The
3.3.0 top-level names among these are in the table of names that are gone.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `building.DbHrAssessment`, `DbHrCheck`, `DbHrGlobalIndexResult` and `DbHrRequirement`, `noise_control.HvacWarning`, `underwater.StrikeSelSpectrum` | `DBHRAssessment`, `DBHRCheck`, `DBHRGlobalIndexResult`, `DBHRRequirement`, `HVACWarning`, `StrikeSELSpectrum` |
| the module `building.measurement.lab_insulation` | `building.measurement.laboratory_insulation`; importing from `building` is unchanged |
| `HMLRatingResult.subject_h`, `.subject_m` and `.subject_l` | `.subject_high`, `.subject_medium` and `.subject_low`, the values per subject beside `high`, `medium` and `low` |
| `.std` on `TrendTestResult` and `StationarityTestResult`, `TimeDelayResult.delay_std` | `.standard_deviation`, `.delay_standard_deviation` |
| `StationarityTestResult.count` | `.trend_statistic`, the `statistic` of the trend test it ran |
| `num_points=` on `verify_filter_class`, and `FilterComplianceResult.num_points` | `n_points` |
| `AnpAircraft.num_engines` and `PerformanceAircraft.engines` | `ANPAircraft.n_engines` and `PerformanceAircraft.n_engines` |
| `blade_count=` on `fan_sound_power`, and the `blades` of `blade_passing_frequency` | `n_blades` |
| `count=` on `precision_positions` | `n_positions=` |
| `count=` on `circular_duct_cut_on` and `rectangular_duct_cut_on`, and `WestonRegimeBoundaries.mode_count` | `n_modes` |
| `count=` on `diffuser_sound_power` | `n_devices=` |
| `harmonics=` on `gear_mesh_frequencies` and `blade_pass_frequencies`, and the `count` of `FaultFrequencyResult.harmonics` | `n_harmonics` |
| `SawtoothBurstTest.burst_count` | `.n_bursts` |
| `room.MAXIMUM_DIRECTIVITY_STEP_DEG`, `MINIMUM_BANDWIDTH_TIME_PRODUCT`, `MINIMUM_DETECTOR_MULTIPLE` and `MINIMUM_REFERENCE_DISTANCE_M`, `noise_control.MAXIMUM_PASSAGE_ASPECT`, `MINIMUM_FLOW_RATES` and `MINIMUM_PRESSURE_DIFFERENCE_PA`, `emission.MINIMUM_BACKGROUND_MARGIN_DB` | `MAX_DIRECTIVITY_STEP_DEG`, `MIN_BANDWIDTH_TIME_PRODUCT`, `MIN_DETECTOR_MULTIPLE`, `MIN_REFERENCE_DISTANCE_M`, `MAX_PASSAGE_ASPECT`, `MIN_FLOW_RATES`, `MIN_PRESSURE_DIFFERENCE_PA`, `MIN_BACKGROUND_MARGIN_DB` |
| `OperatingLine.maximum_deviation`, `maximum_open_loop_gain` and `maximum_level_at_microphone` on `FeedbackStabilityResult`, `maximum_reduction_db=` on `end_reflection_loss`, `LoudspeakerCharacteristics.minimum_impedance`, `minimum_load_impedance` on `MicrophoneCharacteristics` and `MicrophoneElectrical`, `DiscretePointIntensityResult.minimum_positions`, `minimum_speed=` on `railway_source_power` | `max_deviation`, `max_open_loop_gain`, `max_level_at_microphone`, `max_reduction=`, `min_impedance_ohm`, `min_load_impedance_ohm`, `min_positions`, `min_speed_kmh=` |
| `building.a_weighted_maximum_impact_level`, `standardized_maximum_impact_level`, `AWeightedMaximumImpactResult` and `StandardizedMaximumImpactResult` | `a_weighted_max_impact_level`, `standardized_max_impact_level`, `AWeightedMaxImpactResult` and `StandardizedMaxImpactResult`: `max` and `min` in every public name, terms of art included |
| `room.minimum_reliable_reverberation_time` and `minimum_receiver_positions` | `min_reliable_reverberation_time` and `min_receiver_positions` |
| `PhaseDecompositionResult.minimum_phase_response` | `.min_phase_response` |
| `maximum_levels=` on `aircraft.event_level` and `noise_contour` | `max_levels=` |
| `ci_lower` and `ci_upper` on `SpectralDensityResult` and `MultitaperSpectralDensityResult` | `confidence_lower` and `confidence_upper`, as on `MethodBSummary` |
| `elements=` on `low_frequency_element_normalized_difference`, and `LowFrequencyElementResult.elements` | `n_elements` |
| `orders=` on `slit_resonance_frequencies`, and the `junctions` of `multi_junction_adjustment` | `n_orders=` and `n_junctions` |
| `open_microphones=` on `feedback_stability` and `open_microphone_correction`, and `FeedbackStabilityResult.open_microphones` | `n_open_microphones` |
| `events=` on `sound_energy_pressure`, `mean_single_event_level`, `sound_energy_in_situ`, `sound_energy_reverberation` and `sound_energy_comparison`, and `.events` on `SoundEnergyResult` and `ReverberationSoundEnergyResult` | `n_events` |
| `reflecting_planes=` on `measurement_positions`, `sound_power_pressure` and `sound_energy_pressure` | `n_reflecting_planes=` |
| `.positions` on `DiscretePointIntensityResult`, and `.positions`, `.subset_positions` and `.additional_positions` on `PartialPowerConcentration` | `.n_positions`, `.n_subset_positions` and `.n_additional_positions` |
| `RollingStock.axles`, `VehicleDescriptor.axles` and the `axles` of `rolling_sound_power` | `n_axles` |
| `sweep_points=` on `verify_weighting_class`, and `WeightingComplianceResult.sweep_points` | `n_sweep_points` |
| `AssumedProtectionResult.subjects` | `.n_subjects` |
| `io.AudioFileInfo.channels` and `.frames` | `.n_channels` and `.n_samples`, the samples per channel, as on `Signal` |
| `quadrature_points=` on `diffuse_field_absorption`, and `sum_terms=` on `helmholtz_resonator_impedance` and `rectangular_duct_properties` | `n_quadrature_points=` and `n_sum_terms=` |
| `repetitions=` on `predict_diffuser_polar_response`, `predicted_diffusion_spectrum`, `metadiffuser_diffusion_spectrum`, `metadiffuser_polar_response` and `plot_qrd_geometry`, and `DiffuserPolarResponse.repetitions` | `n_repetitions` |
| `cycles=` and `repetitions=` on `signals.tone_burst`, `ToneBurstResult.cycles` and `.repetitions`, and `cycles=` on `vibration.sawtooth_burst` and `signal_burst_indications` | `n_cycles` and `n_repetitions` |
| `trials=` on `metrology.monte_carlo`, and `MonteCarloResult.trials` | `n_trials` |
| the `passages` of `silencer_self_noise`, `valve_style_modifier`, `multihole_incipient_cavitation_ratio` and `uniform_passage_style_modifier`, and the `stages` of `stage_level_correction` | `n_passages` and `n_stages` |
| the `steps` of `FDTD2D.run` and `ElasticFDTD2D.run`, and `max_arrivals=` on `underwater.eigenrays` | `n_steps` and `max_n_arrivals=` |
| `simulation.ContourProbe.samples` and `ContourProbe(sim=...)` | `.n_samples`, read-only, and `engine=` |
| `record_every=` and `decimate=` on `FDTD2D.run` and `ElasticFDTD2D.run`, by position or by name | `snapshot_every=` and `snapshot_decimation=`, the names `FDTDRecording` and `ElasticRecording` take for the same two counts, and like them keyword-only: `run(400, 10, 2)` is `run(400, snapshot_every=10, snapshot_decimation=2)` |
| `fdtd_simulation(probes=..., snapshot_every=..., snapshot_decimation=...)` | `fdtd_simulation(FDTDRun(..., recording=FDTDRecording(probes=..., snapshot_every=..., snapshot_decimation=...)))`: what an acoustic run records is one record, the `recording` of the run, as an elastic run's is one `ElasticRecording`; a run without one records only its time axis, as before |
| `fdtd_simulation(c, dx, duration, sources=..., ...)` and `elastic_fdtd_simulation(c_p, c_s, dx, duration, sources=..., rho=..., ...)` | `fdtd_simulation(FDTDRun(c=c, dx=dx, duration_s=duration, sources=..., boundaries=simulation.FDTDBoundaries(sides=..., absorbing_layer_cells=...), ...))` and `elastic_fdtd_simulation(ElasticRun(c_p=c_p, c_s=c_s, dx=dx, duration_s=duration, sources=..., rho=..., ...))`: a simulation is one record, with the same arguments, which takes every field by name and checks them all when it is built. `duration` is `duration_s`, and the acoustic `boundaries=` and `absorbing_layer_cells=` are now one `FDTDBoundaries`, as the elastic ones are one `ElasticBoundaries`; `compute=` stays on the function. A bad argument raises where the run is written, with the same class and the same words, except that a refused duration now names `duration_s` |
| a `boundaries=` of `elastic_fdtd_simulation` that is not an `ElasticBoundaries`, which failed inside the run | refused with `TypeError` when the `ElasticRun` is built |
| an `ElasticRecording` with a malformed probe, an unknown or repeated field or a bad snapshot count, refused only when `elastic_fdtd_simulation` ran it; a `recording=` of another type, which failed inside the run | refused when the record is built, with the same class and the same words, and a probe off the grid still refused by the run; a `recording=` that is not the run's own record (`FDTDRecording` for an `FDTDRun`, `ElasticRecording` for an `ElasticRun`) raises `TypeError` naming it when the run is built |
| `sidebands=` on `gear_mesh_frequencies` and `induction_motor_frequencies`, the `poles`, `rotor_bars` and `slot_harmonics` of `induction_motor_frequencies`, and `lobe_orders=` on `blade_pass_frequencies` | `n_sidebands`, `n_poles`, `n_rotor_bars`, `n_slot_harmonics` and `n_lobe_orders` |
| `years=` on `hearing.nipts` and `htlan` and on `vibration.injury_risk` and `multiple_shock_assessment`, and `.years` on the ISO 1999 results (`NiptsResult` and `HtlanResult` in 3.3.0) and on `MultipleShockResult` | `exposure_duration_years`: a duration names its quantity before its unit |
| `environment.NoisePhase.hours` and `hours=` on `evaluation_period_level`; `hearing.Task.duration_range` and `.duration_samples`, in hours | `duration_hours`; `.duration_range_hours` and `.duration_observations_hours`, since a `_samples` ending reads as a count of samples |
| `seconds=` on `room.sweep_signal`, `inverse_filter` and `shaped_sweep_signal`, on `electroacoustics.synchronized_sweep_signal` and `swept_sine_distortion`, on `signals.noise_signal` and on `speech.stipa_signal`; `duration=` on `room.image_source_rir`, `SweptSineDistortionResult.duration`, and `io.Signal.duration` and `io.AudioFileInfo.duration` (4.0.0rc1); `flat_duration=`, `leading_duration=` and `trailing_duration=` on `materials.adrienne_window`, `StationarityTestResult.segment_duration` and `PileStrikeResult.pulse_duration` | `duration_s`, the spelling the other durations in seconds already had, and `flat_duration_s=`, `leading_duration_s=`, `trailing_duration_s=`, `.segment_duration_s` and `.pulse_duration_s`: a duration ends in its unit |
| `hours=` on `environment.lden` and `ldn` | `period_hours=`, which is now keyword-only |
| `assessment_period_min=` on `environment.impulse_prominence`, and `ImpulseProminenceResult.assessment_period_min` | `assessment_period_minutes`: a trailing `_min` reads as a minimum (`f_min`), so the minute is spelled out, as the hour is |
| `ReportMetadata.source_positions` and `.receiver_positions` | `.n_source_positions` and `.n_receiver_positions` |
| `signal_in=` on `loudness_ecma`, `tonality_ecma`, `roughness_ecma`, `fluctuation_strength_ecma` and `fluctuation_strength`; `signal=` on `loudness_moore_glasberg_time`, on the distortion and noise measurements of `electroacoustics` (`thd`, `thd_plus_noise`, `sinad`, `weighted_thd`, `harmonic_analysis`, `harmonic_distortion`, `dynamic_range`, `idle_channel_noise`, `modulation_distortion`, `difference_frequency_distortion`, `total_difference_frequency_distortion`, `dynamic_intermodulation_distortion`), on `impulsive_sound_adjustment` and `sound_pressure_level_history`, on the human-vibration functions (`running_rms`, `mtvv`, `vibration_dose_value`, `motion_sickness_dose_value`, `crest_factor`, `apply_weighting`, `apply_band_limiting`) and on `room.plot_excitation` | `x` |
| `tone_freq=` on `tone_to_noise_ratio` and `prominence_ratio` | `tone_frequency=`, which, like `resolution_hz=`, is now keyword-only |

A choice reads the same everywhere it is offered. A band set is the integer
`fraction` that `OctaveFilterBank`, `decay_curve` and `sound_intensity` already
took, `3` for one-third octaves and `1` for octaves; the words `"third"`,
`"third-octave"`, `"one-third-octave"` and `"octave"` are refused, and a table
read by band set is keyed by the same integer. A free, a diffuse and a
pressure field are written `"free"`, `"diffuse"` and `"pressure"`. A frequency
weighting is chosen by `weighting`, and leaving the signal unweighted is
written `"Z"` wherever that is offered: on the sound-level weightings it is the
Z-weighting of IEC 61672-1, and elsewhere it is the response the standard
leaves unweighted, such as the band limitation alone of the DIN 45669-1
vibration meter.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `band=` on `field_incidence_correction`, `mass_law_transmission_loss`, `single_panel_transmission_loss`, `double_wall_transmission_loss`, `orthotropic_transmission_loss`, `short_pulse_mean_square_force`, `tapping_force_spectrum`, `covering_improvement`, `a_weighted_maximum_impact_level` and `cylindrical_shell_modal_density`, and `.band` on `TappingForceResult` and `AWeightedMaximumImpactResult` | `fraction=` and `.fraction`, `3` or `1` |
| `bands=` on `weighted_rating`, `weighted_impact_rating`, `SoundReductionResult.rating`, `facade_sound_reduction`, `normalized_flanking_level_difference`, `normalized_flanking_impact_level`, `calculated_sound_reduction_index`, `reciprocity_impact_level`, `in_situ_element`, `detailed_airborne_prediction` and `detailed_impact_prediction` | `fraction=`; `None` still reads the band set from the values where it did |
| `band_type=` on `sound_power_intensity`, `sound_power_intensity_points`, `position_count_factor` and `determination_standard_deviation` | `fraction=` |
| `bandwidth=` on `tapping_machine_force_level_estimate` | `fraction=` |
| `building.HEAVY_IMPACT_A_WEIGHTING["third"]` and `["octave"]` | `[3]` and `[1]` |
| `"free-field"` and `"diffuse-field"` on `hearing.reference_threshold`, and in `hearing.FIELDS` | `"free"` and `"diffuse"` |
| `curve=` on `filters.weighting_filter` and `WeightingFilter`, `WeightingFilter.curve` and `WeightingComplianceResult.curve` | `weighting=` and `.weighting` |
| `weighted=` on `broadcast.quasi_peak_meter`, and `QuasiPeakResult.weighted` | `weighting="468"` (the default) or `weighting="Z"`, and `.weighting` |
| `weighting=None` on `signals.ln_levels` and `sel` | `weighting="Z"`, now the default |
| `building.PathContribution.fraction`, the share of the transmitted energy a path carries | `.energy_fraction`, so that `fraction` names only a band set |
| `building.DetailedAirborneResult.fractions` and `DetailedImpactResult.fractions`, the share of the energy each path carries in each band | `.energy_fractions` |

## Every public name has one address

A handful of names could be imported from a second module in 3.3.0 or
4.0.0rc1, or from a module that listed something its package did not publish,
and the ANP database put a private name in two constructors. Each name has a
single address now, the one the resolver above returns, and none is private:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `vibration.partial_exposure` | `vibration.daily_exposure`, the function it was a second name for. Called with the value and the duration of one operation, it returns that operation's partial exposure Ai(8), and the number does not move |
| the ISO 717 ratings listed by `building.measurement.insulation`: `weighted_rating`, `weighted_impact_rating`, their `_extended` forms, `weighted_impact_improvement`, `impact_improvement_adaptation_term` and the four rating results | `building.weighted_rating` and the rest, defined in `building.measurement.ratings` |
| `LowFrequencyProcedure` listed by `building.measurement.insulation` | `building.LowFrequencyProcedure`, defined in `building.measurement.low_frequency` |
| the ISO 12354-1 Annex D linings listed by `building.prediction.resilient_layers`: `lining_improvement`, `lining_improvement_in_situ`, `lining_resonance_frequency`, `weighted_lining_improvement`, `LiningImprovementResult` | `building.lining_improvement` and the rest, defined in `building.prediction.linings` |
| `emission.DeclarationForm`; `Grade` and `Surface` listed by `emission.sound_power`; `EQFilterType` listed by `filters.equalizer` (`metrology.equalizer` in 3.3.0) | nothing to import: no type alias is public. Pass the string the parameter takes, `form="single-number"` for instance, and the API reference shows each parameter's `Literal[...]` where the alias used to be |
| `BASIC_METHOD_MAX_CREST_FACTOR` listed by `vibration.human.exposure` | not published. `vibration.crest_factor` warns above 9, the crest factor up to which ISO 2631-1 6.2.2 holds the basic method sufficient |
| `REFERENCE_IMPEDANCE`, `REFERENCE_AREA` and `REFERENCE_SOUND_POWER` of `emission.vibration_sound_power`, a module with no `__all__` whose package never published them | not published. The 400 N·s/m³ and the 1 m² are the defaults of `reference_impedance=` and `reference_area=` in `emission.radiated_sound_power_level`, and the 1 pW is `metrology.REFERENCE_VALUES["gas"]["sound_power"].value` |
| `AnpAircraft(..., _database=db)` and `aircraft._database` | `ANPAircraft(..., database=db)` and `aircraft.database`, still left out of the repr and of comparisons |
| `AnpDatabase(..., performance=...)` (4.0.0rc1) | no `performance=`, whose type nothing published: `aircraft.load_anp_database` reads the performance tables of an export, and a database built by hand flies fixed-point profiles |

```python
from phonometry import building, vibration

# ISO 5349-2 E.3: the brush-saw's partial exposure, 4.6 m/s² for 2 h
print(round(vibration.daily_exposure(4.6, 2 * 3600.0), 1))
print(callable(building.weighted_rating), callable(building.lining_improvement))
print(hasattr(vibration, "partial_exposure"))
# 2.3
# True True
# False
```

## A function is named for what it returns, once

A computation is named for the quantity it gives back, and one computation has
one name. A unit stays in a function's name only where that quantity is
written in more than one unit (`peak_velocity_from_kb_mm_s`,
`air_power_attenuation_per_m`); a level, a correction, an index or a frequency
carries none, because it only ever comes in decibels or hertz. The
root-sum-square of independent uncertainties is one function,
`metrology.combined_standard_uncertainty`, whichever standard prints it, and
the coverage probability of an expanded uncertainty is spelled `coverage`
wherever it is asked for.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `environment.combined_standard_uncertainty(contributions)` | `metrology.combined_standard_uncertainty(contributions)`, the same signature and the same number; a `(u, c)` pair with a negative `u` is now refused |
| `noise_control.combine_stage_levels(80.0, 74.0)`, `noise_control.combine_internal_levels(trim, expander)` | `noise_control.combined_stage_level([80.0, 74.0])`, `noise_control.combined_internal_levels([trim, expander])`: the levels come as one sequence, as every other energy sum takes them |
| `building.energy_average_level(levels, 0)`, `room.directivity_energy_average(levels, 0)` | `axis=0`, by name |
| `materials.PUBLISHED_AIR` | `materials.ABSORBER_AIR`, the dry air at 20 °C the absorber models default to, with the same values. The `PUBLISHED_` prefix belongs to the catalogues, and the name no longer credits the air to the Johnson-Champoux-Allard model, whose book prints another |
| `metrology.combine_uncertainty(model, quantities)` | `metrology.uncertainty_propagation(model, quantities)`, with the same arguments |
| `metrology.expanded_uncertainty(result, 0.95)` | `result.expanded(0.95)`, the method of the result it took |
| `environmental.expanded_uncertainty(u, confidence=0.95)`, the ISO 1996-2 one, which the top level of 3.3.0 published as `environmental_expanded_uncertainty` | `environment.environmental_expanded_uncertainty(u, coverage=0.95)`, with the same number: 2.4 dB for a `u` of 1.2 dB. The top-level `expanded_uncertainty` of 3.3.0 was another function, the ISO 12999-1 one, which gives 2.352 dB for the same `u`; the table of gone names says where it went |
| `coverage_factor(0.95, one_sided)` at the top level of 3.3.0 | `building.insulation_coverage_factor(0.95, one_sided=...)`, the ISO 12999-1 factor it forwarded to. `metrology.coverage_factor(coverage, dof)` is another function, the GUM factor from Student's t, which gives 1.96 to two decimals for 95 % and infinite degrees of freedom and has no one-sided form |

The 3.3.0 top-level names this renames or removes (`combine_uncertainties`,
`combine_uncertainty`, `expanded_uncertainty`, `combine_linings`,
`combine_subareas`, `combine_partial_exposures`, `combine_age_and_noise`,
`air_attenuation_m`, `attenuation_from_alpha` and
`air_attenuation_coefficient`) are in the table of the names that are gone,
at the end of this page.

```python
from phonometry import metrology, noise_control

# ISO 1996-2:2017 Table G.2, the five products c_j u_j of one hour by a road
print(round(metrology.combined_standard_uncertainty([0.59, 0.3, 2.0, 0.40, 0.38]), 2))
print(round(noise_control.combined_stage_level([80.0, 80.0]), 2))
# 2.18
# 83.01
```

## A level or a level difference carries no unit suffix

A level and a level difference are in decibels by definition (a loudness level
is in phon), so a public name whose head noun is one carries no `_db`, whether
it is a parameter, a field, a property, a method or a constant. The head noun
is the last noun of the name, past the words that qualify it from behind (a
band, a frequency weighting, `before` or `after`, `max` or `min`): a level, a
loss, an insulation, an isolation, a reduction, a rejection, a difference, an
improvement, a single-value attenuation, a correction, an adjustment, an
index, the spectrum adaptation term of ISO 717, a shift or an excess of the
level the name names (`level_shift`), or the printed symbol of one of them. A
name whose head noun does not say decibel keeps the suffix: a tolerance, a
margin, an uncertainty, a deviation, a step, a slope or a rate
(`tolerance_db`, `background_margin_db`, `expanded_uncertainty_db`,
`slope_db_per_decade`, `attenuation_db_per_m`). A notebook table still shows
a number under such a name in decibels, now read from its head noun, and a
loudness level in phon; a flag, a text, a complex factor or a record under
one shows no unit, and a number the head noun would misread (the reflection
index of EN 1793-5, the A_eta of IEC 60534-8-3) shows its own. Most of the
names this renames are newer than 4.0.0rc1; the ones that shipped are these.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `MicrophoneCharacteristics.sensitivity_level_db`, `diffuse_field_sensitivity_level_db`, `directivity_index_db`, `equivalent_noise_level_db`, `noise_band_levels_db`, `max_spl_db` and `distortion_spl_db`; `MicrophoneNoise.equivalent_level_db`, `MicrophoneOverload.spl_db`, `MicrophoneDirectivity.index_db` | `sensitivity_level`, `diffuse_field_sensitivity_level`, `directivity_index`, `equivalent_noise_level`, `noise_band_levels`, `max_spl`, `distortion_spl`; `equivalent_level`, `spl`, `index` |
| `LoudspeakerCharacteristics.sensitivity_level_db`, `reference_level_db`, `directivity_index_db` and `spl_db`, `spl_db=` on `loudspeaker_characteristics`, `LoudspeakerDirectivity.index_db` | `sensitivity_level`, `reference_level`, `directivity_index`, `spl`, `spl=`, `index` |
| `QuasiPeakResult.level_db`; `level_db=` on `stipa_signal` and `fluctuation_strength_am_noise` | `level`, `level=` |
| `WindowMetricsResult.scalloping_loss_db` and `worst_case_processing_loss_db`, `SynchronousAverageResult.noise_reduction_db`, `ResampledSignalResult.stopband_attenuation_db` and `stopband_attenuation_db=` on `resample_signal` | `scalloping_loss`, `worst_case_processing_loss`, `noise_reduction`, `stopband_attenuation`, `stopband_attenuation=` |
| `EmissionPressureResult.level_db`, `measured_level_db`, `background_correction_db` and `local_correction_db`, the same three parameters of `emission_sound_pressure_level`, `measured_level_db` and `background_level_db` on `background_noise_correction_at_workstation`, `local_correction_db` on `grade_from_local_correction`, `environmental_correction_db` and `directivity_index_db=` on `environmental_ratio_from_k2` and `environmental_ratio_from_absorption` | `level`, `measured_level`, `background_correction`, `local_correction`, `background_level`, `environmental_correction`, `directivity_index=` |
| `noise_control.MODAL_FILTER_ATTENUATION_DB` | `MODAL_FILTER_ATTENUATION` |
| `emission.MAX_K3_DB` and `GRADE_2_MAX_K3_DB`, the cap on the local environmental correction $K_3$ and its grade 2 bound | `MAX_K3`, `GRADE_2_MAX_K3` |
| `sound_reduction_index_db` on `environment.airborne_insulation_rating` | `sound_reduction_index` |

```python
from phonometry import signals

metrics = signals.window_metrics("hann")
print(round(metrics.scalloping_loss, 2), round(metrics.worst_case_processing_loss, 2))
# 1.42 3.18
```

## A name says the quantity it holds

A name that put `_db` after words that only qualify it (`corrected_db`,
`floor_db`, `threshold_db`, `mean_db`) said the unit of a number and never
what the number is. Each now carries the noun of what it holds. A level takes
`level` or `levels` and then loses its `_db` by the rule of the section above
(`threshold_level`, `corrected_levels`, `emission_levels`), a level
difference takes its own noun (`floor_level_difference`, `mean_attenuation`,
`min_isolation`), and any other quantity keeps `_db` after its noun
(`fixture_uncertainty_db`, `lower_tolerance_db`, `prominence_limit_db`). A
name without decibels takes the noun of its quantity too: a tolerance is a
bound a value has to stay within, and no value is held to the ± 50 % that
ISO 4866 D.2 calls typical of an empirical prediction of a building's
fundamental frequency, so it is named an error. Most of these names are newer
than 4.0.0rc1; the ones that shipped are these.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `psychoacoustics.ToneAssessment.criterion_db` | `prominence_limit_db` |
| `signals.WindowMetricsResult.highest_sidelobe_db` | `highest_sidelobe_level` |
| `broadcast.KWeightingResponse.shelf_db` and `highpass_db` | `shelf_magnitude_db` and `highpass_magnitude_db`, beside `magnitude_db` |
| `signals.LifterResult.liftered_db` | `liftered_spectrum_db`, beside `spectrum_db` |
| `operating_db=` on `emission.total_standard_deviation` | `sigma_omc_db=`, the name every sound power function gives the standard deviation of the operating and mounting conditions |
| `polar_db` of `electroacoustics.MicrophoneCharacteristics` and `electroacoustics.LoudspeakerCharacteristics` | `polar_response_db` |
| `vibration.EMPIRICAL_FREQUENCY_TOLERANCE` | `EMPIRICAL_FREQUENCY_ERROR`, the same 0.5, beside the `empirical_frequency_bounds` that applies it |

```python
from phonometry import emission, signals

print(round(signals.window_metrics("hann").highest_sidelobe_level, 1))
# -31.5
print(emission.total_standard_deviation(1.5, sigma_omc_db=2.0))
# 2.5
```

## A module is never hidden behind a function of its own name

Twenty-three modules of 4.0.0rc1 shared their name with the function their
package published: `signals/correlation.py` sat beside `signals.correlation()`.
The package attribute is the function, so `import
phonometry.signals.correlation as m` bound the function,
`signals.correlation.time_delay` raised `AttributeError`, and only `from
phonometry.signals.correlation import time_delay` reached the module. Each of
those modules is private now. The function keeps its name, every name the
package published from the module keeps its address, and the only thing gone is
the import through the file path:

| 4.0.0rc1 | 4.0 |
| --- | --- |
| `from phonometry.signals.correlation import time_delay` | `from phonometry.signals import time_delay` |
| `from phonometry.fluids.air import air` | `from phonometry.fluids import air`, or `fluids.air(...)` after `from phonometry import fluids` |
| `broadcast.program_loudness`, `emission.sound_power_anechoic`, `emission.sound_power_in_duct`, `emission.sound_power_in_situ`, `emission.sound_power_intensity`, `emission.sound_power_intensity_points`, `emission.sound_power_reverberation`, `fluids.air`, `materials.absorbers.airflow_resistance`, `noise_control.duct_path`, `psychoacoustics.quality.fluctuation_strength`, `psychoacoustics.quality.fluctuation_strength_ecma`, `psychoacoustics.quality.roughness_ecma`, `psychoacoustics.quality.tonality_ecma`, `psychoacoustics.quality.tone_audibility`, `room.crowd_noise`, `room.impulse_response`, `signals.cepstrum`, `signals.correlation`, `signals.envelope`, `underwater.propagation.seabed_reflection`, `vibration.structural.junction_transmission`, `vibration.structural.radiation_efficiency` as module paths | the package before the last dot, which publishes the function and its companions: `from phonometry.room import impulse_response, mls_impulse_response` |
| the numbers those modules kept for themselves: the gates and block lengths of `broadcast.program_loudness` (`ABSOLUTE_GATE`, `RELATIVE_GATE`, `BLOCK_DURATION`, `BLOCK_OVERLAP`, `SHORT_TERM_DURATION`, `MAX_METER_STEP`, `LRA_RELATIVE_GATE`, `LRA_PERCENTILES`), `DEFAULT_SELF_NOISE_FLOOR` of `noise_control.duct_path`, and `SIGMA_NARROWBAND_LEVEL` and `COVERAGE_FACTOR_90` of `psychoacoustics.quality.tone_audibility` | not published, as before: their packages never took them up. Each comes from the document its module follows, and the function that reads it applies it or takes it as the default of `self_noise_floor=`, `sigma_level_db=` or `coverage_factor=`. The 0.1 s step is the period of the 10 Hz update rate EBU Tech 3341 requires, and the 0 dB floor is the default of the worked duct-path sheet in Long's *Architectural Acoustics* |
| the prominence thresholds `PROMINENT_TONALITY_TU_HMS`, `PROMINENT_ROUGHNESS_ASPER` and `PROMINENT_FLUCTUATION_STRENGTH_VACIL` of the ECMA-418-2 modules | `psychoacoustics.PROMINENT_TONALITY_TU_HMS`, `psychoacoustics.PROMINENT_ROUGHNESS_ASPER` and `psychoacoustics.PROMINENT_FLUCTUATION_STRENGTH_VACIL_HMS`, the last with the `_HMS` of its unit, since `psychoacoustics` also publishes the Osses fluctuation strength in plain vacil. No function applies them: compare the result yourself. ECMA-418-2 clause 6.3 calls a tonality prominent when, for a stationary sound, `specific_tonality` exceeds 0.4 tu_HMS at a local maximum whose entry in `tonal_frequencies` lies between the centre frequencies one Bark_HMS below and above, or, for a non-stationary sound, when `tonality` exceeds 0.4 tu_HMS. Clause 7.2 calls a roughness prominent when `roughness` exceeds 0.2 asper, and clause 9.2 a fluctuation strength when `fluctuation_strength` exceeds 0.2 vacil_HMS |

In 3.3.0 several of them lived elsewhere (`metrology/correlation.py`,
`psychoacoustics/tone_audibility.py`); the package import is the answer there
too.

`signals.test_signals` (4.0.0rc1) is private as well, for another reason:
pytest collects a module whose name starts with `test_`, and the prefix belongs
to test files. Every function it held keeps its `signals.` address, so `from
phonometry.signals.test_signals import noise_signal` is `from
phonometry.signals import noise_signal`.

The type aliases those modules defined went with them, and no public path
reaches them now: `PrecisionSurface`, `PrecisionArray` and `PrecisionRoom` of
`emission.sound_power_anechoic`, `MicrophoneShield` of
`emission.sound_power_in_duct`, `Grade` and `BandType` of
`emission.sound_power_intensity`, and `DeterminationGrade` and `BandType` of
`emission.sound_power_intensity_points`. Annotate with the `Literal` each stood
for: `Literal["sphere", "hemisphere"]` for `PrecisionSurface`, and so on.
`BandType` named a band set, which is now the integer `fraction`:
`Literal[1, 3]`.

```python
from phonometry import room, signals

print(callable(signals.correlation), callable(signals.time_delay))
print(callable(room.impulse_response), callable(room.mls_impulse_response))
# True True
# True True
```

### And every public module says what it publishes

A module without `__all__` says nothing about which of its names are public,
so a constant it defined for its own use looked as public as its functions,
and some of them reached guides and scripts through the full module path. Every
public module now lists what it defines and its package publishes, and anything
else it defines takes a leading underscore. These names were reachable that
way in 3.3.0 or 4.0.0rc1 and are not any more:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `OCTAVE_BANDS`, `NC_INDICES` and `NC_CURVES` of `room.noise_criteria` (`room.room_noise` in 3.3.0) | `room.NC_OCTAVE_BANDS_HZ`, `room.NC_RATINGS` and `room.NC_CURVE_LEVELS`, published with their unit: the ten bands of ANSI/ASA S12.2 Table 1, its twelve designations and their band levels |
| `BAND_CENTERS`, `BAND_IMPORTANCE`, `REFERENCE_INTERNAL_NOISE` and `VOCAL_EFFORTS` of `speech.sii` (`hearing.sii` in 3.3.0) | `speech.sii_procedure("one-third-octave")`, whose `frequencies`, `band_importance` and `internal_noise` are the same arrays, and `speech.standard_speech_spectra().vocal_efforts` |
| `NIPTS_FREQUENCIES` of `hearing.noise_induced_hearing_loss` | the `frequencies` of the `hearing.nipts(...)` result |
| `VALIDATED_YEARS`, `VALIDATED_FRACTILES` and `VALIDATED_L_EX_MAX` of the same module | not published. `nipts` and `htlan` warn outside the 1 to 40 years, the 0.05 to 0.95 fractiles and the 100 dB ISO 1999 validates |
| `OCTAVE_BANDS` of `noise_control.hvac` and of `room.enclosed_space_absorption` | not published: each is the default band axis of its functions, and every result carries its `frequencies` |
| `SPEED_OF_SOUND`, `AIR_ATTENUATION` and `PUBLISHED_AIR_CONDITION` (`DEFAULT_AIR_CONDITION` in 3.3.0) of `room.enclosed_space_absorption` | not published: the 345.6 m/s default of `speed_of_sound=`, and the six conditions `air_condition=` takes, which its docstring lists, `"20C_50-70"` the one clause 4.3 recommends |
| `REFERENCE_VELOCITY`, `REFERENCE_FORCE`, `REFERENCE_SOUND_POWER` and `FREE_VELOCITY_REFERENCE` of `building.measurement.structure_borne_power` (`building.structure_borne_power` in 3.3.0), and `REFERENCE_PRESSURE` of `environment.assessment.impulsive_sound` (`environmental.impulsive_sound` in 3.3.0) | the `.value` of the `metrology.REFERENCE_VALUES` entry each was read from, since the entry is a record and not a number: `["solid"]["velocity"].value` (1 nm/s), `["solid"]["force"].value` (1 µN), `["gas"]["sound_power"].value` (1 pW), `["solid"]["velocity_alternative"].value` (the 50 nm/s of note b of Table 3, the ISO 9611 free-velocity reference) and `["gas"]["sound_pressure"].value` (20 µPa) |
| `REFERENCE_MOBILITY` and `CHARACTERISTIC_PLATE_MOBILITY` of `building.measurement.structure_borne_power` (`building.structure_borne_power` in 3.3.0), and `REFERENCE_PLATE_MOBILITY` of `building.prediction.installed_structure_borne` (`building.installed_structure_borne` in 3.3.0) | not published. `REFERENCE_MOBILITY` is the 1 m/(N s) reference mobility of EN 15657 clause 5, which the functions apply in its Formulae (15), (17) and (18); the plate mobility is the default of `characteristic_mobility=` and `plate_mobility=` |
| `SPEED_OF_SOUND`, `AIR_DENSITY`, `REFERENCE_FREQUENCY`, `REFERENCE_LENGTH` and `MAX_RADIATION_FACTOR` of `building.prediction.detailed_model` | not published. The air is `building.EN12354_AIR`, which carries the 340 m/s and the 1.29 kg/m³ |
| the coefficients, limits and defaults of `environment.assessment.impulsive_sound` (`environmental.impulse_prominence` and `environmental.impulsive_sound` in 3.3.0): `PROMINENCE_COEFFS`, `ADJUSTMENT_SLOPE`, `ADJUSTMENT_THRESHOLD`, `ONSET_RATE_LIMIT`, `DEFAULT_ASSESSMENT_PERIOD_MIN`, `ONSET_GRADIENT_LIMIT`, `TIME_WEIGHTING_F_TAU`, `MERGE_GAP`, `SAMPLE_INTERVAL_RANGE`, `DEFAULT_SAMPLE_INTERVAL`, `HIGHLY_IMPULSIVE_LIMIT` | not published: each is applied by `impulse_prominence` or `impulsive_sound_adjustment`, and the two defaults are those of `dt=` (20 ms) and `assessment_period_minutes=` (30 min) |
| the Annex C constants of `vibration.human.multiple_shock` (`vibration.multiple_shock_vibration` in 3.3.0): `MZ_MALE`, `MZ_FEMALE`, `DOSE_AMPLITUDE_FACTOR`, `DOSE_EXPONENT`, `GRAVITY`, `ULTIMATE_STRENGTH_INTERCEPT`, `STRENGTH_AGE_SLOPE_MALE`, `STRENGTH_AGE_SLOPE_FEMALE`, `WEIBULL_MALE`, `WEIBULL_FEMALE`, `RISK_THRESHOLDS_MALE`, `RISK_THRESHOLDS_FEMALE` | not published: the functions take `sex=` and apply the pair it names. `compression_dose(..., mz=)` defaults to 0.029, the male value of Formula C.2; pass 0.025 for the female one |
| `DEFAULT_HEADWIND_KT` and `APPROACH_WEIGHT_FRACTION` of `aircraft.flight_performance` | not published: the 8 kt default of `Aerodrome(headwind_kt=)`, and the 0.9 of the maximum landing weight the approach is flown at |
| `STANDARD_ATMOSPHERIC_PRESSURE` of `materials.resilient.dynamic_stiffness` (`materials.dynamic_stiffness` in 3.3.0) | not published: the 0.1 MPa default of `static_pressure_pa=` |
| `REFERENCE_SPACING` of `emission.intensity_compliance` | not published: the 25 mm nominal microphone separation of IEC 61043 Table 2, the default of `spacing_m=` of `residual_index_limits` and `verify_intensity_class` |
| `DISTRIBUTIONS` of `metrology.uncertainty` | not published: `metrology.Quantity` refuses a `distribution=` outside `"gaussian"`, `"rectangular"`, `"triangular"` and `"u-shaped"` and names the four |
| `CIRCULAR_EIGENVALUES`, `PLANE_WAVE_EIGENVALUE` and `warn_above_plane_wave_limit` of `noise_control.duct_modes` | `noise_control.circular_duct_cut_on` and `noise_control.plane_wave_limit`; the silencer and duct-path results raise `PlaneWaveWarning` above the limit themselves |
| `WALL_ORDER` of `room.image_source` | not published: a per-wall `absorption=` is in the order `x0`, `xL`, `y0`, `yL`, `z0`, `zL` |
| `MAX_ENUMERATED_LATTICE` of `room.modes`, `SAMPLE_RATE` of `speech.objective_intelligibility` (`hearing.objective_intelligibility` in 3.3.0) | not published: a lattice limit `room_modes` states when it refuses, and the 10 kHz `speech.stoi` resamples to |
| `AUDIBILITY_THRESHOLD_SONE_HMS` of `psychoacoustics.loudness_ecma` (3.3.0) | `psychoacoustics.AUDIBILITY_THRESHOLD_SONE_HMS`; `psychoacoustics.loudness.ecma.AUDIBILITY_THRESHOLD_SONE_HMS`, its 4.0.0rc1 address, still imports. No function applies it: ECMA-418-2 clause 5.1.9 calls a signal audible when its total basis loudness, the specific basis loudness summed over the 53 bands (Formula 26), exceeds 0.01 sone_HMS, and `loudness_ecma` returns that total block by block as `basis_loudness_vs_time`, the field to compare up to its `last_evaluated_block`; its `loudness` is the N of Formula 117, not that sum |
| `J1_FIRST_ZERO` of `electroacoustics.piston` | gone: nothing read it. It is `scipy.special.jn_zeros(1, 1)[0]` |
| `critical_bandwidth` of `environment.sources.wind_turbine` (`environmental.wind_turbine_noise` in 3.3.0) | the `critical_bandwidth` of the `WindTurbineTonalityResult`. `environment.critical_bandwidth` is another band, the ISO 1996-2 one |
| `reference_sound` of `psychoacoustics.quality.sharpness` (`psychoacoustics.sharpness` in 3.3.0) | not published: the library builds the DIN 45692 clause 6 test signal only to fix its own normalization. It is noise band-limited to 920 to 1080 Hz at 60 dB: pass `signals.noise_signal(fs, duration_s)` through a 920 to 1080 Hz band-pass and scale it to 0.02 Pa rms, and `psychoacoustics.sharpness_din` gives it 1.00 acum |
| `check_guidance` of `underwater.bioacoustics.weighting` | not published. The functions that take `guidance=` refuse an unknown one, and `underwater.WEIGHTING_GUIDANCE` names the known ones |

The type aliases these modules define (`NCMethod`, `EventMetric` and the rest)
are not listed either, by the rule above, and stay importable as annotations.

```python
from phonometry import hearing, room, speech

print(room.NC_CURVE_LEVELS[room.NC_RATINGS == 40][0][:3])
print(round(speech.sii_procedure("one-third-octave").band_importance.sum(), 6))
print(hearing.nipts(95.0, 40.0, 0.9).frequencies[:3])
# [84. 74. 64.]
# 1.0
# [ 500. 1000. 2000.]
```

## Every `.plot()` takes the axes first

Every result's `.plot()` now reads `plot(ax=None, *, ...)`: the axes first,
and every other argument by name, `language` included. Three did not start
with the axes in 3.3.0, so `plot(ax)` on them handed the axes to the wrong
parameter:

| 3.3.0 | 4.0 |
| --- | --- |
| `LoudspeakerCharacteristics.plot("impedance", ax)` | `.plot(ax, quantity="impedance")` |
| `MicrophoneCharacteristics.plot("noise", ax)` | `.plot(ax, quantity="noise")` |
| `TransferMatrix.plot(f, rho_c, ax)` | `.plot(ax, frequencies=f, characteristic_impedance=rho_c)` |

Six results that are newer than 3.3.0 took `language` by position in
4.0.0rc1: the four hearing-protector ratings and the two low-frequency
intensity results. `plot(ax, "es")` on those is `plot(ax, language="es")`
now, as it is everywhere else.

The public `plot_*` helpers, which draw a device or a geometry rather than a
result, share one shape now as well: what they draw by position, and the
axes, the language and the style keywords by name,
`plot_x(<data>, *, ax=None, ..., language="en", **kwargs)`. Seventeen took the
axes after their data and six took them first. `plot_silencer_geometry` also
took every dimension as a keyword of its own; it takes the `kind` and the
`geometry` a `ReactiveSilencerResult` keeps now, the dimensions in one mapping
under the same keys, so the drawing reads like the result:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `vibration.plot_plate_geometry(0.8, 0.6, ax)`, `environment.plot_barrier_geometry(ax, source_height=...)` and the other twenty-one public `plot_*` helpers | `plot_plate_geometry(0.8, 0.6, ax=ax)`, `plot_barrier_geometry(ax=ax, source_height_m=...)` |
| `noise_control.plot_silencer_geometry("expansion chamber", ax, length=0.3, chamber_area=0.04, pipe_area=0.01)` | `plot_silencer_geometry("expansion chamber", {"length": 0.3, "chamber_area": 0.04, "pipe_area": 0.01}, ax=ax)` |

## A multi-panel `.plot()` returns a tuple of axes

A `.plot()` that draws more than one panel returns, without `ax`, a tuple of
its axes, the top panel first, where 3.3.0 and 4.0.0rc1 returned a NumPy
array of them. Indexing, unpacking and `len()` work as before; the array's
own attributes do not:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `axes = result.plot()`, then `axes.shape` or `axes.size` | `len(result.plot())` |
| `result.plot().flat`, `result.plot().ravel()` | the tuple itself: `for ax in result.plot()` |
| `isinstance(drawn, np.ndarray)`, to tell several panels from one axes | `isinstance(drawn, tuple)` |

With `ax` the plot draws one panel on it and returns that axes, as before.
Each case is a typed overload now, so a type checker reads
`top, bottom = result.plot()` as two `Axes` and `result.plot(ax=ax)` as one.
`ZwickerLoudness.plot()` without `ax` still returns one axes for a stationary
result and two for a time-varying one, which only the data decide.

The plots that draw on a polar axes say so. `PistonDirectivity`,
`VectorChangeResult` and `DiffuserPolarResponse` return a `PolarAxes`, and so
do `DiffusionResult.plot()` without `ax`, `DirectivityFactor.plot()` for its
`"response"` view, and `LoudspeakerCharacteristics.plot()` and
`MicrophoneCharacteristics.plot()` for `quantity="directivity"`. Those take a
`PolarAxes` where they need one; matplotlib types a subplot made with
`projection="polar"` as plain `Axes`, so a typed caller hands it over as
`typing.cast(PolarAxes, ax)`. `DiffuserPolarResponse.plot()` refuses a
cartesian axes with a `ValueError` that names `ax`, as the other polar plots
do, where it raised an `AttributeError` from matplotlib.

## A zero-dimensional array gives a zero-dimensional array

A function of a number or an array of them returns a `float` only when every
argument that decides the shape of its result is a number, a Python or a
NumPy one, and an array as soon as one of them is a sequence or an array,
where 3.3.0 and 4.0.0rc1 returned a `float` for a zero-dimensional array,
and a zero-dimensional array, a NumPy scalar or a one-element array for
numbers. Three hundred and fifty-two public functions and methods follow the
rule, `room.room_constant`, `room.critical_distance` and
`fluids.sea_water_sound_speed` among them, and `vibration.evaluation_zone`
follows it with a zone letter where the others give a `float`, and a complex
result (a mobility, an impedance, a transfer function) with a Python
`complex`:

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `room.room_constant(100.0, np.array(0.2))` returned the `float` `25.0` | it returns `array(25.)`; `float(...)` or `.item()` gives the number |
| `emission.local_environmental_correction([0.5])` returned a `float` for any one-element input, as did `emission.environmental_ratio_from_k2`, `emission.environmental_ratio_from_absorption`, and the `background_margin_db` field and the `correction` property of the `WorkstationBackgroundCorrection` that `emission.background_noise_correction_at_workstation` returns | each gives a one-element array; hand over `0.5`, not `[0.5]`, to get a number |
| `electroacoustics.piston_resistance(1.0)` returned a `numpy.float64`, as did `piston_reactance` and `piston_directivity` | it returns a Python `float`, with no `.shape` or `.dtype` |
| `building.mass_law_transmission_loss(500.0, 10.0)` returned a zero-dimensional array, as did 61 other functions and methods listed below | it returns a Python `float`; `np.asarray(...)` gives an array where one is wanted |
| `materials.absorption_coefficient(4.0, 2.0, 200.0, 11.0)` returned a `numpy.float64`, as did 7 others listed below | it returns a Python `float`, with no `.shape` or `.dtype` |
| `building.composite_transmission_loss([10.0, 2.0], [40.0, 25.0])` returned a zero-dimensional array, as did `building.total_structure_borne_pressure_level([30.0, 35.0])`, `materials.reverberation_time_uncertainty` and `emission.mean_single_event_level` with `n_events=None` | each returns a `float` when it reduces to one number |
| `building.survey_service_equipment_level([30.0, 31.0, 32.0], 0.5, volume=50.0)` held a zero-dimensional array in `l_xy` and a `numpy.float64` in `l_xy_nt` and `l_xy_n` | the three levels are Python `float`s for single readings |
| `vibration.sdof_mobility(100.0, 1.0, 1.0e4, 5.0)` returned a zero-dimensional `complex128` array, as did 18 other functions listed below | it returns a Python `complex`; `np.asarray(...)` gives an array where one is wanted |
| `materials.membrane_impedance(500.0, surface_density=1.0)` returned a one-element complex array, as did 8 other functions listed below | it returns a Python `complex`, and a zero-dimensional array gives a zero-dimensional one |
| `building.bending_radiation_factor(500.0, critical_frequency=100.0, length1=4.0, length2=3.0)` returned a one-element array, as did 69 other functions and methods listed below, whose check made a number one-dimensional | it returns a Python `float`, and a zero-dimensional array gives a zero-dimensional one |

The functions and methods that returned a zero-dimensional array for numbers
are, besides `building.mass_law_transmission_loss`:
`aircraft.MeanGroundPlaneResult.height`; in `building`,
`background_correction`, `low_frequency_level`,
`characteristic_reception_plate_power`, `equivalent_blocked_force_level`,
`equivalent_free_velocity_level`, `source_mobility_from_levels`,
`structure_borne_power_level`, `transmission_loss_from_coefficient`,
`coupling_term`, `coupling_term_force_source`,
`coupling_term_velocity_source`, `installed_power_from_reception_plate`,
`installed_structure_borne_power_level`,
`structure_borne_pressure_level_path`, `structure_to_airborne_adjustment`,
`tapping_machine_characteristic_power_level`,
`tapping_machine_coupling_term`, `tapping_machine_force_level_estimate`,
`force_pulse` and `typical_element_mobility`; in `emission`,
`normal_intensity_from_levels`, `phase_mismatch_from_residual_index`,
`residual_index_from_phase_mismatch`, `background_noise_correction`,
`radiated_sound_power_level`, `radiation_factor`, `velocity_level` and
`velocity_level_from_acceleration`; in `environment`, `air_attenuation`,
`kurze_anderson_attenuation` and `EffectiveSoundSpeedProfile.speed_at`; in
`materials`, `absorption_from_reflection`, `absorption_reference_corrected`,
`air_density_iso10534`, `normalized_diffusion_coefficient`,
`scattering_coefficient`, `speed_of_sound_iso10534`,
`speed_of_sound_iso17497`, `standing_wave_absorption`,
`standing_wave_ratio_from_level`, `standing_wave_reflection_magnitude`,
`statistical_absorption`, `tube_attenuation_constant`,
`absorption_coefficient_uncertainty`, `base_plate_scattering`,
`random_incidence_absorption` and `specular_absorption_coefficient`;
`signals.comb_filter_response`; and in `vibration`,
`corner_transmission_coefficient`, `straight_transmission_coefficient`,
`coupling_loss_factor`, `point_connection_coupling_loss_factor`,
`wave_vibration_reduction_index`, `random_error_percent`,
`transfer_stiffness_level`, `loss_factor`, `beam_bending_wave_speed`,
`plate_bending_wave_speed`, `injected_power` and `phase_tolerance_deg`
(`phase_tolerance_degrees` in 4.0.0rc1). Those that returned a NumPy scalar
are, besides `materials.absorption_coefficient`:
`building.surface_pressure_intensity_indicator` and
`building.reverberation_index`; `environment.predicted_prominence` and
`environment.impulse_adjustment`; `materials.absorption_area`;
`room.hard_object_absorption`; and `vibration.ultimate_strength`. A
zero-dimensional array given to any of them gives a zero-dimensional array,
and the values are the same.

The complex results that returned a zero-dimensional array for numbers are,
besides `vibration.sdof_mobility`: in `materials`,
`normalized_surface_impedance`, `normalized_surface_admittance`,
`surface_impedance`, `reflection_factor`, `tube_wavenumber`,
`standing_wave_reflection` and `standing_wave_normalized_impedance`; and in
`vibration`, `sdof_receptance`, `sdof_accelerance`, `convert_frf`,
`infinite_beam_impedance`, `infinite_beam_mobility`,
`infinite_beam_moment_mobility`, `base_transmissibility`,
`blocking_force_ratio`, `transfer_stiffness_direct`,
`transfer_stiffness_indirect` and `seat_to_spine_transfer`. Those that
returned a one-element complex array are, besides
`materials.membrane_impedance`:
`environment.spherical_reflection_coefficient`; in `materials`,
`perforated_plate_impedance`, `microperforated_plate_impedance` and
`helmholtz_resonator_impedance`; in `noise_control`, `helmholtz_impedance`
and `quarter_wave_impedance`; `simulation.far_field_from_contour`; and
`underwater.reflection_coefficient`. The real results that returned a
one-element array are, besides `building.bending_radiation_factor`: in
`aircraft`, `atmospheric_adjustment`, `diffraction_attenuation`,
`ground_effect_adjustment`, `npd_level` and `ANPNPDCurves.level`
(`AnpNpdCurves.level` in 3.3.0 and 4.0.0rc1); in `building`,
`acceleration_level`, `band_mode_count`, `bare_floor_impact_level`,
`calculated_sound_reduction_index`, `direct_impact_level`,
`direct_reduction_index`, `direction_averaged_level_difference`,
`equivalent_absorption_length`, `fast_reverberation_correction`,
`flanking_impact_level`, `flanking_impact_level_from_flanking_level`,
`flanking_impact_level_from_normalized_difference`,
`flanking_reduction_index`, `flanking_reduction_index_from_flanking_level`,
`flanking_reduction_index_from_normalized_difference`,
`floating_floor_improvement`, `forced_radiation_factor`,
`in_situ_equivalent_absorption_length`, `in_situ_impact_level`,
`in_situ_reduction_index`, `in_situ_total_loss_factor`,
`in_situ_velocity_level_difference`, `laboratory_total_loss_factor`,
`modal_overlap_factor`, `normalized_ceiling_attenuation`,
`partition_referenced_reduction_index`, `plate_loss_factor`,
`reciprocity_impact_level`, `resilient_mount_improvement`,
`resonant_sound_reduction_index`, `short_pulse_mean_square_force`,
`structural_reverberation_time`, `total_loss_factor`,
`velocity_level_difference` and `vibration_reduction_index_from_flanking`;
`electroacoustics.weighting_bs468` (`itu_r_468_weighting` in 3.3.0 and
4.0.0rc1); in `emission`, `flow_modal_correction` and
`in_duct_reproducibility`; in `environment`, `fresnel_number`
(`environmental.fresnel_number` in 3.3.0) and `line_source_segment_power`;
in `hearing`, `earphone_reference_level`, `hearing_level_to_coupler_spl` and
`reference_threshold`; `materials.spot_internal_loss_correction`; the
`peak_exceedance` and `peak_density` of `metrology.PeakStatisticsResult`; in
`noise_control`, `band_internal_levels`, `cavitation_distribution`,
`duct_sound_power_level`, `flow_noise_power_level`,
`measured_transmission_loss`, `open_end_reflection_coefficient`,
`open_end_transmission_loss`, `substitution_insertion_loss`,
`transmission_loss_correction` and `turbulent_distribution`; in
`underwater`, `seawater_absorption`, `spreading_loss`,
`thermal_noise_spectrum` and `wind_noise_spectrum`; and in `vibration`,
`band_limiting_factors`, `beam_modal_density`,
`cylindrical_shell_modal_density` and `weighting_factors`. A sequence or an
array given to the argument that decides the shape, a one-element one
included, gives the array it gave, and the values are the same. A per-band
argument that rides beside the frequencies decides nothing of its own: the
structural reverberation time of `building.total_loss_factor` and
`building.equivalent_absorption_length` and the reverberation time of
`building.plate_loss_factor` (with `frequency=` for the first two in
4.0.0rc1), given as a one-element sequence or a zero-dimensional array
beside a number frequency, gave a one-element array and give a `float` now.
Without frequencies, `hearing.reference_threshold` and
`hearing.earphone_reference_level` give every band of their table, as
before.

These arrived after 4.0.0rc1 and follow the rule from the start, with a
`complex` for numbers: `electroacoustics.program_signal_filter`; in
`materials`, `microphone_calibration_factor` and
`apply_microphone_calibration`; in `metrology`,
`microphone_acoustic_impedance`, `temperature_transfer_function`,
`air_gap_series_impedance_pa_s_m3`, `free_field_transfer_impedance`, the
`acoustic_impedance_pa_s_m3` and `complex_equivalent_volume_m3` of
`ReciprocityMicrophone` and the `response_at` and `record_response_at` of
`TimeSelectiveResponse`; and in `vibration`, `kb_weighting_response`,
`band_limitation_response` and the `fitted_frf`, `corrected_frf` and
`corrected_mobility` of `SingleModeFitResult`; and with a `float`: in
`electroacoustics`, `band_limit_response`, `field_strength`,
`field_strength_level`, `magnetic_flux_density`, `telecoil_response`,
`AmplifierFrequencyResponse.at` and the `at` and `drive_voltage` of
`LoopImpedance`; in `emission`, `reverberation_parameter`,
`special_room_background_correction`, `air_absorption_np_per_m`,
`free_field_absorption_correction`, `directionality_tolerance`,
`inverse_square_law_tolerance`, `min_analyzer_bandwidth`,
`plant_air_absorption_db_per_m`, `reverberation_background_correction`,
`room_absorption_coefficient`, `room_constant_from_air_absorption`,
`room_constant_from_reverberation_time`, `radiation_impedance_correction`,
`reference_source_reproducibility` and the `sound_power_level_at` of
`ReferenceSourceCalibration`; in `environment`,
`air_power_attenuation_per_m`, `barrier_background_correction` and
`redistributed_band_energies`; in `hearing`, `age_and_noise_threshold`,
`incidence_correction` and `reat_expanded_uncertainty`; in `io`, the
`values_at` of `BandedRow` and of the catalogue rows of `materials`,
`building` and `noise_control`; in `materials`,
`power_attenuation_from_alpha`, `air_density_astm_e2611`,
`speed_of_sound_astm_e2611`, `in_situ_absorption_from_reflection`,
`air_absorption_correction` and `reproducibility_uncertainty`; in
`metrology`, `max_expanded_uncertainty`, the `level_at` and `spectrum_at` of
`RectangularPulse` and the `level_at` and `phase_deg_at` of
`TimeSelectiveResponse`; in `noise_control`, `flow_velocity_m_s`,
`insertion_level_difference`, `reverberant_surface_area_m2`,
`screen_background_corrected_level`, `silencer_background_correction`,
`silencer_sound_power_level`, `transmission_level_difference` and
`velocity_pressure_pa`; in `room`, `corrected_distribution_value`,
`floor_reference_value`, `level_excess`, `reference_distribution_value` and
`sound_distribution_value`; and in `vibration`,
`assessment_weighting_response`, `blast_peak_velocity_mm_s`,
`elastic_insertion_loss`, `far_field_velocity_mm_s`,
`foundation_to_floor_level_difference`,
`ground_attenuation_coefficient_per_m`, `ground_transmission`,
`impact_peak_velocity_mm_s`, `kb_weighted_levels`,
`machine_count_correction`, `machine_hall_velocity_mm_s`,
`material_damping_factor`, `passage_energy_spectral_density`,
`predict_floor_spectrum`, `rescale_emission_for_speed`,
`spectral_density_level`, `train_kb_fmax`, `train_velocity_ratio`,
`velocity_psd_from_voltage` and `velocity_spectrum_um_s`. A per-band
argument beside the frequencies of these, such as the sound power levels of
`room.sound_distribution_value`, the level differences of
`vibration.predict_floor_spectrum` and the exponent of
`vibration.ground_transmission`, decides nothing of its own, and gives a
`float` beside a number frequency as a one-element sequence too.

Three hundred and sixteen of them have typed overloads, so a type checker
reads `room.room_constant(100.0, 0.2)` as a `float` and
`room.room_constant(100.0, alphas)` as an array whatever the shape of
`alphas`; an `ArrayLike` or a nested list reads as the union, which a typed
caller narrows. The reducers (`signals.leq` and the other levels of a
signal, `building.energy_average_level`, `room.directivity_energy_average`
and their kin), whose result is one number for a one-dimensional input, keep
the union and their behaviour. The four flanking paths of the detailed
building model (`building.flanking_reduction_index`,
`building.flanking_impact_level` and their two forms from a normalized
difference), five or six of whose arguments broadcast, and
`building.vibration_reduction_index_from_flanking`, five of whose arguments
broadcast too, keep the union in their signature and follow the rule when
they run.

The four-pole matrices of `noise_control` follow the rule with a matrix in
place of a number. `noise_control.duct_matrix(500.0, 0.3, 0.05)` returned a
stack of one matrix, of shape `(1, 2, 2)`, as did
`noise_control.shunt_matrix` for one impedance; both return the `(2, 2)`
matrix alone for a number or a zero-dimensional array now, and the
`(n_freq, 2, 2)` stack for a sequence or an array, a one-element one
included, as before. `noise_control.cascade` multiplies matrices alone into
a matrix, which 4.0.0rc1 refused, and stacks into a stack, and refuses a
matrix alone beside a stack with a `ValueError`;
`noise_control.transmission_loss` and `noise_control.insertion_loss` return
a `float` for a matrix alone, where they raised an `IndexError`, and one
value per frequency for a stack. `matrix[np.newaxis]` makes a stack of one,
which gives the one-element array it gave; the values are the same.

## A sample rate is a `float`, and a count takes a NumPy integer

The rate of a `Signal` is the `float` it was given, so a type checker reads
`sig.fs` as a `float`, where it read an `int`, and every function that runs
at any positive rate takes a `float`: the rate one function returns is the
rate the next one takes. The functions that need a whole number of samples
per second keep refusing a fractional one: `io.write`, which writes the rate
into the file's header, the test signals of `electroacoustics`,
`electroacoustics.field_strength_meter`, `room.image_source_rir`,
`psychoacoustics.loudness_zwicker`, `psychoacoustics.sharpness_din`,
`psychoacoustics.psychoacoustic_annoyance_from_signal` and `speech.stoi`.
`vibration.evaluate_train_passage`, `signals.resample_signal` handed a Signal
and the Method B bank of `environment` refused a fractional rate as well, on
the grounds that the filter bank needed a whole one, which it does not: they
run at any rate.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `psychoacoustics.loudness_zwicker(x, sig.fs)` type checked, `sig.fs` read as an `int` | hand over the Signal, `loudness_zwicker(sig)`, or `int(sig.fs)` |
| `io.write(path, io.Signal(x, 44100.5))` failed inside the header with `struct.error` | it raises `ValueError` naming `fs`, as `fs=44100.5` does |
| `filters.OctaveFilterBank(fs, order=2.5)`, `room.mls_signal(10.5)` and the other counts checked only as one number ran with a fraction or a bool | a fraction raises `ValueError: 'order' must be a whole number`, a bool a `TypeError`; pass the whole number |
| `emission.sound_intensity(p1, p2, fs, spacing_m=d, fraction=1.0)` ran | it raises `TypeError`, as every band fraction does; pass `1` or `3` |

A count, a band fraction or a flag takes the NumPy integer or truth value
its validator takes (`int | np.integer[Any]`, `BandFraction |
np.integer[Any]`, `bool | np.bool_`), and values by band take a mapping keyed
by integers (`{125: 40.0}`) as they take one keyed by floats. A count that
was checked only as one number is read by the same whole-number check, so a
fraction or a bool it used to take is refused, as in the rows above. A result
record that validates a count or a band fraction holds the `int` it reads,
where it kept a NumPy integer as it was given.

## A parameter that takes numbers refuses a text before the call runs

A parameter that takes numbers was annotated with NumPy's `ArrayLike`, which
admits any `str` and any `bytes`, so `signals.leq("not a signal")` type
checked in mypy and pyright and only the call refused it. Every such
parameter, field and declared constructor now takes `NumericArrayLike`, a
number, a sequence of numbers nested to any depth, or a NumPy array, or
anything with an `__array__`, of a numeric or boolean dtype, and no text. A
list, a tuple, a nested list, an array of any numeric dtype and a Signal
type check as before, and the calls run as they ran.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `signals.leq("not a signal")` type checked, and the call raised `TypeError` | a type checker refuses it, and the call raises the same `TypeError` |
| `levels: ArrayLike = load(); signals.leq(levels)` type checked | a type checker refuses it, since `ArrayLike` says a text may be there; annotate `levels` with what it holds, `NDArray[np.float64]`, `Sequence[float]` or `float` |
| `view = memoryview(samples); signals.leq(view)` type checked | a type checker refuses it, as it refuses a `ctypes` array or another object that offers its numbers only through the buffer protocol, while the call runs as it ran; pass `np.asarray(view)` |

The labels of `environment.statistical_pass_by` (`vehicle_categories`) and
the `sites` of the soundscape summaries of `environment` keep `ArrayLike`:
they take texts.

## Verdicts are result objects, not dictionaries

The three `verify_*` functions of 3.3.0 returned `dict[str, Any]` and now
return a frozen dataclass, like every other result in the library.
`filter_class_compliance`, the public wrapper that existed only to package the
filter verdict, went with the change, since the verifier now returns the
object itself. Each key of the dictionary is an attribute of the same name,
but for `passed`, which is `passes`, and every argument after the one the call
is about is written by name.

| 3.3.0 | 4.0 |
| --- | --- |
| `verify_filter_class(bank)["overall_class"]` | `filters.verify_filter_class(bank).overall_class` |
| `verify_filter_class(bank, 4096)` | `filters.verify_filter_class(bank, n_points=4096)` |
| `verify_weighting_class(wf)["overall_class"]` | `filters.verify_weighting_class(wf).overall_class` |
| `verify_aircraft_noise_system(...)["passed"]` | `aircraft.verify_aircraft_noise_system(...).passes` |
| `filter_class_compliance(bank)` | `filters.verify_filter_class(bank)`, which returns the same `FilterComplianceResult` |

`verify_intensity_class` and `verify_quasi_peak_dynamics` are newer than
3.3.0, and in 4.0.0rc1 they already returned their records.

```python
from phonometry.filters import OctaveFilterBank, verify_filter_class

verdict = verify_filter_class(OctaveFilterBank(48000, fraction=1, limits=[125, 4000]))
print(verdict.overall_class, len(verdict.bands))
```

`verify_running_rms_decay` is newer than 3.3.0, and in 4.0.0rc1 it returned a
bare `bool`, which threw away the printed interval and the measured time it
had judged. It now returns a `RunningRMSDecayVerification` that keeps both:
the verdict is `.passes`, beside `.measured_time_s`, `.printed_time_s`,
`.tolerance_s` and the interval as `.lower_time_s` and `.upper_time_s`. The
object refuses to be read as a truth value, so an
`if verify_running_rms_decay(...):` written against the release candidate
raises `TypeError` instead of passing every meter.

## A verdict says `passes`, refuses a truth value, and comes from a verb

A judgement is named for what it judges: `verify_` an instrument, `assess_` a
measured situation, `check_` the setup a method needs. Each returns a record
that keeps its reasons, and a pass or a fail is spelled `passes` on every one of
them. A record a judging function returns, and every record with a `passes`,
refuses to be read as a truth value: `if verdict:` raises `TypeError` and the
message names what to read. In 3.3.0 and 4.0.0rc1 these records were always
true, so an `if` written against them passed every failure: read `.passes` on
`QuasiPeakDynamicsResult`, `AircraftSystemComplianceResult`,
`WeightingVerification`, `PhaseVerification`, `SignalBurstVerification`,
`DBHRCheck`, `DBHRAssessment`, `ActivityAssessment` and `PeriodAssessment`;
`.overall_class` on `FilterComplianceResult`, `WeightingComplianceResult` and
`IntensityInstrumentComplianceResult`; `.within_guideline` on
`DamageAssessment`, since exceeding a guideline value of DIN 4150-3 is not a
failure; `.qualified` on `PrecisionCriteria`; `.adjustment` on
`TonalAssessmentResult`; and `.decisive_audibility` or `.audible` on
`ToneAudibilityResult`.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `.complies` on `DbHrCheck`, `DbHrAssessment` (now `DBHRCheck`, `DBHRAssessment`), `ActivityAssessment` and `PeriodAssessment` | `.passes` |
| `vibration.is_significant_change(change, zone_b_upper)` | `vibration.assess_operational_change(change, zone_b_upper).significant`, beside the `.threshold` it is read against. A significant change is a reason to investigate, not a failure, so the flag keeps its name |
| `materials.limp_frame_applicable(k_c, criterion=...)` | `materials.check_limp_frame(k_c, criterion=...).passes`, beside the `.ratio` and the `.threshold`. A ratio exactly on the threshold no longer passes: Allard & Atalla print both criteria as strict inequalities |
| `fi.field_is_stationary(limit=...)` on a `FieldIndicators` | `fi.check_field_stationarity().passes`, and band by band its `.stationary`. The limit is the 0.6 of Table B.3, read as `.limit`, and no longer an argument |
| `room.perceptibly_different(symbol, first, second)` | `room.assess_perceptible_difference(symbol, first, second).different`; the two values must now have the same shape |
| `materials.check_base_plate_scattering(s) == ()` | `materials.check_base_plate_scattering(s).passes`, with the bands over the limit in `.exceeded_frequencies` and the per-band `.margins`, `.exceeds` and `.limits` beside them. A coefficient that is not finite raises `ValueError`, where it used to pass |
| `corrected, limited = building.background_corrected_level(lp, lb)` | `result = building.background_corrected_level(lp, lb)`, then `result.corrected_levels` and `result.limited` |
| `k1, held = emission.background_noise_correction_at_workstation(lp, lb)` | `result = emission.background_noise_correction_at_workstation(lp, lb)`, then `result.correction` and `result.upper_bound` |

The 3.3.0 top-level names this renames (`rigid_mass_calibration_check`,
`satisfies_lower_requirement`, `satisfies_upper_requirement`,
`strong_coupling_satisfied` and `tonal_seeking_survey`) are in the table of
the names that are gone, at the end of this page.

```python
from phonometry import building, materials

conformity = building.assess_requirement_conformity(52.0, 1.5, 50.0, bound="minimum")
print(conformity.passes, conformity.margin_db)
# True 0.5
check = materials.check_base_plate_scattering([0.02] * len(materials.BASE_PLATE_BANDS_HZ))
print(check.passes, check.exceeded_frequencies.size)
# True 0
try:
    bool(check)
except TypeError as error:
    print(type(error).__name__)
# TypeError
```

## The filter bank returns a result, not a tuple

`octave_filter()` and `OctaveFilterBank.filter()` returned two items normally
and three when `sigbands=True` asked for the band waveforms. The length of the
answer depended on a keyword, which is why the pair needed twelve `@overload`
declarations to be typed at all, and why `_, _, bands = bank.filter(...)` was
a line you had to count commas in.

They now return an `OctaveFilterResult` with named fields. The other answers
of the bank that were tuples are records too: the spectrogram is an
`OctaveSpectrogramResult`, and the band set the bank is designed on is read
from attributes spelled out in full.

| 3.3.0 | 4.0 |
| --- | --- |
| `spl, freq = octave_filter(x, fs)` | `r = octave_filter(x, fs)`, then `r.levels` and `r.frequencies` |
| `spl, _ = octave_filter(x, fs)` | `octave_filter(x, fs).levels` |
| `_, freq = octave_filter(x, fs)` | `octave_filter(x, fs).frequencies` |
| `_, _, bands = bank.filter(x, sigbands=True)` | `bank.filter(x, sigbands=True).require_bands()` |
| `levels, freq, times = bank.spectrogram(x)` | `r = bank.spectrogram(x)`, then `r.levels`, `r.frequencies` and `r.times` (an `OctaveSpectrogramResult`, drawn with `r.plot()`) |
| `bank.freq`, `bank.freq_d`, `bank.freq_u`, `bank.nominal_freq`, `bank.num_bands` | `bank.frequencies`, `bank.lower_edges`, `bank.upper_edges`, `bank.labels`, `bank.n_bands`, read-only: the arrays refuse writes and `labels` is a tuple |

```python
import numpy as np
from phonometry import filters

result = filters.octave_filter(np.zeros(8000) + 1e-6, 8000, fraction=3)
print(len(result.frequencies), result.bands)
# 25 None
```

`bands` is `None` unless the call asked for `sigbands=True`, and `levels` is
`None` for a call made with `calculate_level=False`. Code that needs either
one can say so with `require_bands()` or `require_levels()`, which return the
value or raise naming the argument that was missing, rather than handing back
a `None` that fails several lines later.

The result also draws itself, so the band spectrum is one call:

```python
ax = result.plot()
```

## Other answers that were tuples are records

Every other answer that came back as a tuple of different quantities, to be
unpacked by position, is a record with named fields now, and none of them
unpacks: a line that still does raises `TypeError: cannot unpack
non-iterable ...` instead of handing back the wrong column. A tuple is left
only where its items are alike, such as the two ends of a range, lower
first.

| 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- |
| `freq, lower, upper, labels = filters.nominal_frequencies(3)` | `b = filters.nominal_frequencies(3)`, then `b.frequencies`, `b.lower_edges`, `b.upper_edges` and `b.labels` (a `FractionalOctaveBands`) |
| `epnl, pnltm, kf, kl = aircraft.epnl_from_pnlt(pnlt)` | `r = aircraft.epnl_from_pnlt(pnlt)`, then `r.epnl`, `r.pnltm`, `r.band_limits` (the pair `(kF, kL)`), `r.bandsharing_adjustment` and `r.duration_correction` (an `EPNLIntegration`) |
| `freqs, delta_l = building.improvement_octave_bands(dl, f)` | `s = building.improvement_octave_bands(dl, frequencies=f)`, then `s.frequencies` and `s.values` (an `OctaveBandSpectrum`, whose `quantity` says what the values are) |
| `freqs, values = result.octave_bands()` on a `building.FloorCoveringImprovementResult` | `result.octave_bands().frequencies` and `.values`, the same `OctaveBandSpectrum` |
| `l_in, s_m = building.combine_subareas(l_in, areas)` | `r = building.subarea_intensity_level(l_in, areas)`, then `r.levels` and `r.measurement_area` (a `SubareaIntensityLevel`) |
| `freqs, u = band_uncertainty.to_arrays()` on a `building.BandUncertainty` | `band_uncertainty.frequencies` and `band_uncertainty.uncertainties`, the fields it was read from |
| `bx, bz, bxz = building.corrugated_plate_stiffness(...)` | `b = building.corrugated_plate_stiffness(...)`, then `b.b_x_n_m`, `b.b_z_n_m` and `b.b_xz_n_m` (a `CorrugatedPlateStiffness`) |
| `f, lower, upper = building.heavy_impact_source_limits(source)` | `lim = building.heavy_impact_source_limits(source)`, then `lim.frequencies`, `lim.lower` and `lim.upper` (a `HeavyImpactSourceLimits`) |
| `width, k = building.wall_tie_stiffness(tie)`, `building.WALL_TIE_STIFFNESS[tie][1]` | `t = building.wall_tie_stiffness(tie)`, then `t.cavity_width_m` and `t.stiffness` (a `WallTieStiffness`, which is also what each row of `WALL_TIE_STIFFNESS` holds) |
| `result.ratings` on a `building.LiningImprovementResult` | `result.delta_rw`, `result.delta_ra` and `result.delta_ratr`, the fields the tuple was read from |
| `f, gamma2 = electroacoustics.coherence(x, y, fs)` | `c = electroacoustics.coherence(x, y, fs)`, then `c.frequencies` and `c.coherence` (a `CoherenceResult`, with `.plot()`) |
| `f, levels = emission.octave_band_levels(levels, f)` | `o = emission.octave_band_levels(levels, frequencies=f)`, then `o.frequencies` and `o.levels` (an `OctaveBandLevels`, with `.plot()`) |
| `f, class_1, class_2 = emission.residual_index_limits(device)` | `lim = emission.residual_index_limits(device)`, then `lim.frequencies`, `lim.class_1` and `lim.class_2` (a `ResidualIndexLimits`) |
| `wavelengths, levels = environment.wheel_roughness(brake)`, and the same of `rail_roughness`, `contact_filter` and `impact_roughness_single` | `w = environment.wheel_roughness(brake)`, then `w.wavelengths_mm` and `w.levels` (a `WavelengthSpectrum`, with `.plot()`) |
| `source_a, source_b = environment.traction_sound_power(vehicle)`, and the same of `aerodynamic_sound_power` | `p = environment.traction_sound_power(vehicle)`, then `p.source_a` and `p.source_b` (a `RailSourceSpectra`) |
| `RollingStock(wheel_roughness=(wavelengths, levels), traction=(a, b), ...)`, `RailwayTrack(rail_roughness=(wavelengths, levels), ...)` | the same fields given a `WavelengthSpectrum(wavelengths_mm=..., levels=...)` or a `RailSourceSpectra(source_a=..., source_b=...)`; a bare pair raises `TypeError` naming the field |
| `f, lower, upper = filters.weighting_class_limits(1)` | `lim = filters.weighting_class_limits(1)`, then `lim.frequencies`, `lim.lower` and `lim.upper` (a `WeightingClassLimits`) |
| `rho, kappa = materials.slit_effective_properties(f, ...)`, and the same of `rectangular_duct_properties` | `p = materials.slit_effective_properties(f, ...)`, then `p.effective_density` and `p.bulk_modulus` (an `EffectiveFluidProperties`) |
| `fc, alpha = materials.one_third_octave_absorption(alpha, f)` | `b = materials.one_third_octave_absorption(alpha, frequencies=f)`, then `b.frequencies` and `b.absorption` (a `OneThirdOctaveAbsorption`, with `.plot()`) |
| `a, b, c, d = materials.wave_decomposition(...)`, `p0, pd, u0, ud = materials.face_quantities(...)` | `w = materials.wave_decomposition(...)` with `w.a` to `w.d` (a `WaveAmplitudes`), `q = materials.face_quantities(...)` with `q.p0`, `q.pd`, `q.u0` and `q.ud` (a `FaceQuantities`) |
| `k, U = result.expanded(0.95)` on a `metrology.UncertaintyResult` | `e = result.expanded(0.95)`, then `e.coverage_factor` and `e.expanded_uncertainty` (an `ExpandedUncertainty`) |
| `f, spl = psychoacoustics.equal_loudness_contour(40.0)`, `f, tf = psychoacoustics.hearing_threshold()` | `c = psychoacoustics.equal_loudness_contour(40.0)`, then `c.frequencies`, `c.levels` and `c.phon`, which is `None` for the threshold (a `LoudnessContour`, with `.plot()`) |
| `f, v = vibration.foundation_guideline_curve(building_class)` | `g = vibration.foundation_guideline_curve(building_class)`, then `g.frequencies` and `g.velocities_mm_s` (a `GuidelineCurve`) |
| `chi, psi = vibration.junction_wave_parameters(...)` | `w = vibration.junction_wave_parameters(...)`, then `w.chi` and `w.psi` (a `JunctionWaveParameters`) |
| `time, level = room.decay_curve(ir, fs)`, which still unpacked | `curve = room.decay_curve(ir, fs)`, then `curve.times` and `curve.levels` (a `DecayCurve`, which no longer unpacks) |
| `times, levels = environment.sound_pressure_level_history(x, fs)` | `h = environment.sound_pressure_level_history(x, fs)`, then `h.times` and `h.levels` (a `LevelHistory`, which no longer unpacks) |

```python
import numpy as np
from phonometry import aircraft, filters

bands = filters.nominal_frequencies(1, [125, 1000])
print(bands.labels)
# ('125', '250', '500', '1k')

epnl = aircraft.epnl_from_pnlt(np.array([90.0, 95.0, 90.0]), 0.5)
print(epnl.band_limits, round(epnl.duration_correction, 2))
# (0, 2) -10.88
```

The octave spectrum draws itself with `.plot()`, labelled by its quantity.

## Tolerance limits come lower first, and signed

`vibration.weighting_tolerance_percent` returned the Table 5 band of
ISO 8041-1 as `(upper, lower)`, and the three constants
`CENTRAL_TOLERANCE_PERCENT`, `SKIRT_TOLERANCE_PERCENT` and
`TAIL_TOLERANCE_PERCENT` held `(upper %, lower %, phase °)`. Every other pair of
limits in the library is `(lower, upper)`, so these two now are too. The lower
limit stays negative, as the table prints it, and `-100.0` still means that
the standard sets no lower limit.

This one changes no name and raises nothing: `upper, lower = ...` still
unpacks two arrays, and swaps them. Read every unpacking of the four:

| 4.0.0rc1 | 4.0 |
| --- | --- |
| `upper, lower = vibration.weighting_tolerance_percent(name, f)` | `lower, upper = vibration.weighting_tolerance_percent(name, f)` |
| `vibration.CENTRAL_TOLERANCE_PERCENT == (12.0, -11.0, 6.0)` | `(-11.0, 12.0, 6.0)` |
| `vibration.SKIRT_TOLERANCE_PERCENT == (26.0, -21.0, 12.0)` | `(-21.0, 26.0, 12.0)` |
| `vibration.TAIL_TOLERANCE_PERCENT == (26.0, -100.0, inf)` | `(-100.0, 26.0, inf)` |

```python
from phonometry import vibration

lower, upper = vibration.weighting_tolerance_percent("Wk", [16.0])
print(lower, upper)
# [-11.] [12.]
```

## A record's fields are required

Several records carried fields that defaulted to `None`, so that a result
built by hand from a few of its numbers would still construct. Every reader
then had to ask whether the field was there: the fiche refused a bare rating
only once a report was asked for, and a plot of the geometry raised that the
result "does not retain its geometry". The fields are required now, and a
record built without one, or with `None` for one (`dataclasses.replace`
included), raises `TypeError` naming it.

| Record | Required now |
| --- | --- |
| `building.AirborneInsulationResult` | `l1`, `l2`, `t2`, `t0` |
| `building.ImpactInsulationResult` | `li`, `t2`, `t0` |
| `building.WeightedRatingResult`, `building.ImpactRatingResult` | `frequencies`, `measured`, `shifted_reference` |
| `building.ExtendedWeightedRatingResult`, `building.ExtendedImpactRatingResult` | `frequencies`, `measured` |
| `building.ApertureTransmissionResult` | `depth`, now the fourth field; and `width_m` for a slit or `radius` for a circular aperture |
| `building.FacadePredictionResult` | `elements`, now the sixth field |
| `emission.IntensityResult` | `spacing_m`, keyword-only |
| `environment.BarrierInsertionLoss` | `source_height_m`, `barrier_distance`, `barrier_height_m`, `receiver_distance`, `receiver_height_m`, keyword-only |
| `psychoacoustics.ZwickerLoudness` | `field` (`"free"` or `"diffuse"`), now the fourth field, before `n5` |
| `room.OpenPlanResult` | `positions_m`, the distances the metrics were fitted on |
| `materials.LayeredAbsorberResult` | `layers`, the stack the prediction was solved for |
| `materials.DiffuserPolarResponse` | `well_width` and `n_repetitions`, keyword-only; `depths` stays optional, because a response predicted from an explicit `reflection` has none |
| `materials.MetadiffuserResult` | `wells`, `depth_m` and `period_m`, the panel the reflection was solved for, keyword-only |
| `materials.SlitResonatorAbsorberResult` | `resonators`, `slit_height_m`, `lattice_step_m` and `period_m`, the panel the prediction was solved for, keyword-only |
| `materials.ImpedanceTubeResult` | `spacing_m` and `x1`, the microphone spacing and the distance from the sample to the farther microphone, which the reduction cannot run without, keyword-only; `diameter_m` stays optional, because it need not be supplied |
| `materials.InSituAbsorptionResult` | `source_height_m` and `microphone_height_m`, the set-up the absorption was measured with, keyword-only |
| `vibration.JunctionTransmissionResult` | `thickness1_m` and `thickness2_m`, the plates of the junction, keyword-only |
| `noise_control.ReactiveSilencerResult` | `plane_wave_limit`, and exactly one of `geometry` (a named device) and `chain` (a `SilencerChain`); `resonances`, `geometry`, `plane_wave_limit` and `chain` are keyword-only |

`simulation.FDTDResult` and `simulation.ElasticFDTDResult` take two more
fields, after the others: `snapshot_decimation`, every how many cells a
snapshot keeps along each axis (1 for every cell, as before), and
`provenance`, the `simulation.RunProvenance` of where the run stepped. A
result built by hand passes both, and leaving one out raises `TypeError`
naming it; the results the simulation functions return carry both already. A
`RunProvenance` built by hand passes every field, `phonometry_version`, the
version of the phonometry that ran the steps, among them.

`filters.WeightingFilter(..., high_accuracy=None)` used to select the
default. `high_accuracy` is a plain `bool` now, `True` by default, and `None`
raises `TypeError` rather than being read as false, which would pick the plain
design.

`building.CeilingAttenuationResult.rounded` was a field the caller passed in.
It is read from `measured` now, rounded to the nearest integer as ASTM E413
clause 5.2 asks (the clause leaves a half open, and the library rounds
it up), so it cannot disagree with the data;
leave it out when building the record by hand.

## Waveforms inside results come back as the `Signal` they came from

A transform handed a `Signal` has returned a `Signal` since the contract was
written, but five result objects still stored their waveform as a bare array
next to a loose `fs`. They now keep the type the input arrived as:

| Field | Is a `Signal` when the input was one |
| --- | --- |
| `envelope(...).signal` | at the input's rate |
| `time_synchronous_average(...).period_waveform` | at the input's rate |
| `resample_signal(...).signal` | at `fs_new` |
| `align_impulse_responses(...).aligned`, `.reference` | each one if its own input was |
| `underwater.pile_strike_metrics(...).pressure` | at the input's rate |

A bare array in still gives a bare array out, so code that passes arrays does
not notice. Code that passes a `Signal` and does arithmetic on one of these
fields goes through `np.asarray`, as it does for any `Signal`, and a
calibrated input comes back with `calibration_factor=1.0`, so the field feeds
the next function in pascals without the factor being applied again.

## A block stream yields `Signal` blocks

`io.read_blocks` is newer than 3.3.0, and in 4.0.0rc1 it yielded bare float64
arrays. It now yields a `Signal` per block, carrying the rate, the
calibration, the channel labels and the provenance `io.read` gives, and it
takes the same `calibration_factor=` and reads the same sidecar. Two things
change for a loop written against the release candidate. A block from a
calibrated file reaches the filters and the level functions in pascals, so a
`calibration_factor` applied by hand on top of it counts twice. And
arithmetic on a block, or on what a filter returns for one, goes through
`np.asarray`, as it does for any `Signal`.

## Published tables refuse writes

Every table the library publishes at module level is read-only in 4.0. In
3.3.0 published tables were plain dictionaries and published arrays took
in-place arithmetic, so a line such as `REFERENCE_CURVE[500] = 0.9` or
`BAND_IMPORTANCE *= 2` changed the number for every caller that ran after it
in the same process, and nothing raised. The dictionaries are now
`types.MappingProxyType`, including the ones nested inside another table, and
the arrays have their `writeable` flag cleared. Reading is unchanged; writing
raises `TypeError` on a table and `ValueError` on an array.

Code that adjusted a published table has to copy it first:

```python
from phonometry import room
from phonometry.materials.absorbers import REFERENCE_CURVE

curve = dict(REFERENCE_CURVE)
curve[4000] = 1.0
curves = room.NC_CURVE_LEVELS.copy()
curves[0, 0] = 0.0
print(REFERENCE_CURVE[4000], curve[4000], curves[0, 0], room.NC_CURVE_LEVELS[0, 0])
# 0.9 1.0 0.0 78.0
```

A table with tables inside it needs each level copied, as in
`{area: dict(rows) for area, rows in GUIDE_VALUES.items()}`. The same copy is
needed before a table is pickled, deep-copied or written out as JSON, because
a read-only mapping supports none of the three.

## A result keeps its own copy of the arrays it was given

In 3.3.0 and in 4.0.0rc1 a result kept the very array it was handed whenever
that array was already of the type the function reads, `float64` for levels
and frequencies, because `np.asarray` hands its argument back unchanged in
that case. Changing the caller's array afterwards, `levels[0] = 0.0` or
`frequencies *= 2`, changed a result already computed and perhaps already
printed. In 4.0 every array that a function or a method of the library
keeps from the arguments it was given is a copy of its own, made read-only
like the published tables, and the caller's array is left as it was. That
holds for the objects that keep arrays to hand out later as well: the
frequency grid of a `noise_control.SilencerChain`, the axes and flight paths
an `aircraft.ANPDatabase` is built from, and the medium maps of
`simulation.FDTD2D` and `simulation.ElasticFDTD2D`, whose `c`, `rho`, `c_p`
and `c_s` now stay the ones the time step was computed from. The maps the
engines derive from them, `FDTD2D.kappa` and `ElasticFDTD2D.mu` and `.lam`,
are read-only NumPy copies too: in 4.0.0rc1 an edit to one reached part of the
step and not the time step, and now it raises `ValueError`, so a different
medium is a new engine built from edited maps. A `Signal`
keeps a copy of its own samples too, which stays writeable for processing in
place, as the samples of a file read with `io.read` always were. A result
record built by hand, by calling its class directly, makes the same copy:
every public record that can hold an array copies the arrays it is handed
when it is built, whoever builds it, also inside a tuple, a list or any
mapping. A record held inside another one is kept whole and answers for its
own arrays, and a `Signal` is no exception: the seven results that hand a
waveform back as a `Signal` (`filters.OctaveFilterResult`,
`signals.EnvelopeResult`, `signals.ResampledSignalResult`,
`signals.AlignedImpulseResponseResult`, `signals.SynchronousAverageResult`,
`environment.DirectSoundSubtraction` and `underwater.PileStrikeResult`) hold
one of their own when the library builds them, whose samples stay writeable
like any `Signal`'s, and hold the caller's own when built by hand around it.
Every other array a result holds refuses in-place writes, the ones it
computed as well as the ones it was given, where in 3.3.0 most computed
arrays took them. Writing into one now raises `ValueError`, so code that
edited one in place has to copy it first:

```python
import numpy as np

from phonometry import io, room

levels = np.array([60.0, 58.0, 55.0, 52.0, 50.0, 48.0, 45.0, 42.0, 40.0, 38.0])
nc = room.noise_criterion(levels)
levels[0] = 0.0
samples = np.zeros(4)
signal = io.Signal(samples, fs=48_000)
samples[0] = 1.0
measured = np.array([1.0, 0.5, 0.25, 0.125])
response = room.ImpulseResponseResult(ir=measured, fs=48_000, method="farina")
measured[0] = 0.0
edited = nc.levels.copy()
edited[0] = 62.0
print(nc.levels[0], nc.levels.flags.writeable, response.ir[0], response.ir.flags.writeable)
print(signal.data[0, 0], signal.data.flags.writeable)
# 60.0 False 1.0 False
# 0.0 True
```

The window a spectral result was computed with is held the same way.
`signals.power_spectral_density`, `signals.cross_spectral_density`,
`signals.coherent_output_spectrum`, `signals.miso_coherence`,
`signals.spectrogram`, `signals.zoom_fft`, `signals.envelope_spectrum` and
`signals.window_metrics` store the `window` they were given, and a window
given with its parameters keeps parameters of its own: the weights of
`("general_cosine", weights)` given as a list are held as a tuple of the
same numbers, where 3.3.0 held the caller's list, so
`result.window == ("general_cosine", (0.5, 0.5))`; given as an array they
are a read-only copy, as every array a result holds is. A result built by
hand, or anew by `dataclasses.replace`, holds its window the same way.

## A catalogue row says what its source claims for each cell

The published catalogues of materials are new in 4.0: neither 3.3.0 nor
4.0.0rc1 had them. They changed shape once on the way to the final release,
and code written against the main branch in between needs the changes below.
Every row of every catalogue now shares one base, `io.CatalogueRow` (with
`io.BandedRow` for a row that prints one value per band), and the same three
questions have the same answer on any of them.

| Before | 4.0 |
| --- | --- |
| `SolidMaterial.estimated`, `OrthotropicWood.estimated` | `row.basis`, which maps each footnoted field to `"estimated"` |
| `SolidMaterial.is_estimate(field)`, `OrthotropicWood.is_estimated(field)` | `row.basis_of(field) == "estimated"` |
| `row.is_derived(field)` on a value the page gives in a unit the row does not hold (the °F and psi of Ver & Beranek Table 14.1, the sabins of Long Table 7.1) | `field in row.converted`; `row.converted[field]` is the page's figure and its unit, such as `("3e5", "psi")` |
| `row.is_derived(field)` on a value the page gives by reference to another of its rows: a cell left blank under a block (Ver & Beranek Table 8.7, ASHRAE Table 30) or a description that reads "Parecido al anterior" (Harris Chapter 32) | `field in row.carried`; `row.carried[field]` names the row |
| `OrthotropicWood(...)` and `PlateauMaterial(...)` with their own fields by position | every field by name, as on every other row |
| `from phonometry._internal.catalogue import CatalogueRow` | `from phonometry.io import CatalogueRow` |

`is_derived` now answers only for what the library computes and could compute
again from the row's own cells, such as a bar speed worked out from a modulus
and a density. A value the page gives in another unit is still the page's
number, and so is one it gives by reference to another of its rows, so neither
is derived any more. `basis_of` answers with the field's own entry, else the
row's, else an empty string, which means the source does not say how the
number was obtained; the five things a source can claim are in
`io.CATALOGUE_BASES`.

```python
from phonometry import solids

board = solids.PUBLISHED_SOLIDS["hopkins-2007-table-a2/plasterboard_natural_gypsum"]
ear = solids.damping_named("EAR C-1002")[0]
print(board.basis_of("poisson_ratio"))
# estimated
print(ear.converted["youngs_modulus_max_pa"], ear.is_derived("youngs_modulus_max_pa"))
# ('3e5', 'psi') False
```

The resilient layers became catalogue rows in the same change. A
`ResilientLayer` is an `io.CatalogueRow` like every other row, keyed and
credited the way the others are:

| Before | 4.0 |
| --- | --- |
| `PUBLISHED_RESILIENT_LAYERS["mineral_wool_rock_60_30"]`, `resilient_layer("mineral_wool_rock_60_30")` | `"hopkins-2007-table-a3/mineral_wool_rock_60_30"`, the `"<table>/<row>"` key of every catalogue |
| `layer.attributed_to`, a string | `layer.attributed_to["row"]`, a mapping as on every row |
| `ResilientLayer(...)` with the stiffness, the density and the thickness required | every quantity optional, and `apparent_dynamic_stiffness_n_m3` beside `dynamic_stiffness_n_m3` for a source that gives only the apparent $s'_\mathrm{t}$ |
| `layer.natural_frequency(mass_per_area=...)` | `layer.natural_frequency(mass_per_area_kg_m2=...)`; a layer that holds only $s'_\mathrm{t}$ also takes `airflow_resistivity_pa_s_m2=` and `gas_stiffness_n_m3=`, and raises `ValueError` without the first |

Hopkins Table A3 prints $s'$, the stiffness of the installed layer as the
book's own list of symbols defines it, so its fifteen rows still hold
`dynamic_stiffness_n_m3` and return the natural frequencies they returned
before. Four of them hold a density the page prints once for their block and
leaves blank on their own line, and `layer.carried["density_kg_m3"]` now
names the row that prints it; the density is the same.

```python
from phonometry import materials

rebond = materials.resilient_layer("hopkins-2007-table-a3/rebond_foam_64_20")
print(rebond.attributed_to["row"], round(rebond.natural_frequency(mass_per_area_kg_m2=120.0), 1))
# Hopkins and Hall (2006) 43.6
```

## A catalogue row checks itself when it is built

Every catalogue row is checked in its constructor, whether the library builds
it from a packaged table or a caller builds it by hand, and a cell nothing
downstream could read raises `io.CatalogueError`, naming the row and the
field. Code written against the main branch in between that relied on any of
these being accepted has to change:

| Accepted before | 4.0 |
| --- | --- |
| `NaN`, an infinity, `True` or a text such as `"0,97"` in a numeric field | `CatalogueError`; a cell the page leaves empty is `None` |
| a fraction in a whole-number field (`year`), `1` in a flag field (`has_section_drawing`), a number in a text field | `CatalogueError` |
| an empty `name` or `source`, or a hedge whose text is empty, as in `misprinted={"porosity": ""}` | `CatalogueError`; `why_missing` answered `""` for that cell, which hid the hedge |
| a hedge keyed by a field the class does not have, as in `ranges={"no_such_field": ...}`, or a hedge on a number (`ranges`, `approximate`, `unquantified`, ...) keyed by a text field | `CatalogueError`, naming the hedge and the key |
| `bounded_above` or `bounded_below` on a field with no range; a range, or an interval among the `reported` readings, with an end that is not finite or with its low end above its high one; a `reported` list with nothing in it; an `uncertainty` below zero | `CatalogueError` |
| a value beside `misprinted`, `unquantified`, `not_derivable` or `reported` on the same field; a `converted` or `carried` entry on a field that holds nothing | `CatalogueError`: the first four say there is no value to serve, the last two have nothing to describe |
| a value below zero in a field whose name ends in `_kg_m3`, `_kg_m2`, `_kg`, `_kg_mol`, `_m_s`, `_pa`, `_pa_s_m2`, `_pa_s_m`, `_n_m3`, `_mm`, `_um`, `_m`, `_m2`, `_m_hz` or `_per_cm` (a density, a mass per area, a mass, a molar mass, a speed, a pressure or modulus, a flow resistivity, a specific flow resistance, a stiffness per area, a length, an area, a thickness-frequency product, a count per centimetre); a porosity outside 0 to 1; `shot_content_percent`, `binder_content_percent` or `adhered_area_percent` outside 0 to 100 | `CatalogueError`; a Celsius temperature, a decay rate per metre and a level in decibels stay signed |
| `approximate=[...]` kept as the list it was given, a mapping kept as the dict | a `frozenset`, and every mapping frozen all the way down, its pairs into tuples |
| a subclass field annotated with a type the contract has no check for, a bare `float` or `int` included | `TypeError` the first time the class is built; a field is `float \| None` (`Optional[float]` is the same), `int \| None`, `bool`, `str`, `frozenset[str]` or a `Mapping[str, ...]` of those, because every cell of a row may be missing |
| `PorousMaterial.frame_constants()` on a row without `structural_loss_factor`, read as a frame that dissipates nothing | `ValueError`, saying what the page had in that cell |
| `GroundSurface.porosity` holding 26.9 to 58.1 on six rows of Cox & D'Antonio Table 6.7, which the page prints in per cent in a column of fractions that states no unit | `None`, with `misprinted["porosity"]` quoting the figure the page prints; `why_missing("porosity")` and `printed("porosity")` say so |

Every other packaged row already met the contract, so those six porosities are
the only published cells that change, and every published porous row with
both moduli prints its loss factor.

```python
from phonometry import io, materials

try:
    materials.PorousMaterial(name="Panel core", source="a datasheet", porosity=97.0)
except io.CatalogueError as error:
    print(error)
# 'Panel core': porosity is 97.0, and a porosity is a fraction from 0 to 1

carpet = materials.Carpet(
    name="Loop pile", source="a datasheet", pile_height_mm=6.0, approximate=["pile_height_mm"]
)
print(carpet.approximate)
# frozenset({'pile_height_mm'})
```

## A filter bank's class reads every requirement of IEC 61260-1

`verify_filter_class` graded the Table 1 mask alone. For the 2014 edition it
now also grades the effective bandwidth deviation of 5.12 and the summation of
output signals of 5.16, computed as IEC 61260-2:2016 computes them, and a
band's `class` and the bank's `overall_class` are the strictest class met on
all three. For the 1995 edition it grades the filter integrated response of
4.5.3 and the summation of output signals of 4.9 beside Table 1, as that
edition's clause 5 tests them. In both editions every band is graded at the
bank's input rate up to half of it, so a decimated band is graded on the alias
images its decimation folds onto it, and the bank's decimator keeps them more
than 125 dB down.

| Before | 4.0 |
| --- | --- |
| each band of a decimated bank decimated until its processing Nyquist frequency is 1.25 times its upper band edge | decimated only as far as leaves it sixteen times that edge, so the bilinear transform no longer bends the band: a band level moves by up to 0.07 dB on white noise, most in the lowest bands, and the octave bank, which would sum its outputs up to +0.94 dB and read class 2 on 5.16, is class 1 on every requirement |
| a band's `class` read off `margin_class{c}_db` | `class` over every requirement; `margin_class{c}_db` is still the Table 1 margin, beside `bandwidth_margin_class{c}_db` and `summation_margin_class{c}_db`, which is `None` on the two end bands |
| one requirement to ask about | `requirements`, `requirement_class(name)` and `binding_margin(name, cls)` read each one on its own, and `plot(requirement="summation")` draws it |
| an `edition="1995"` verdict on Table 1 alone | Table 1, `"effective_bandwidth"` (the filter integrated response of 4.5.3) and `"summation"` (4.9, run from the lowest to the highest mid-band frequency, so the end bands carry it too), both at the S that 5.3.3 raises in steps of 12 until the integrated response settles, which the result's `points_per_bandwidth` reports (36 for the default octave bank) |
| a decimated band graded up to the Nyquist frequency of its decimated rate, `checked_to_omega` stopping there | graded at the input rate up to half of it, alias images included; `checked_to_omega` is half the input rate over the mid-band frequency, and `range_limited` marks a Table 1 mask running on past it |
| the anti-aliasing filter `scipy.signal.resample_poly` designs by default, which left the images of the octave bank at 8, 16 and 32 kHz 68.9 dB down, under the 70 dB of class 1 | a filter of the same length sized for a 120 dB stopband, its images at least 125.4 dB down; a band level moves by under 0.01 dB |

The octave and one-third-octave banks keep class 1.

```python
from phonometry import filters

octave = filters.verify_filter_class(
    filters.OctaveFilterBank(48000, fraction=1, limits=[125, 4000]))
print(octave.overall_class, octave.requirement_class("relative_attenuation"))
# 1 1
```

## A verdict reads its printed limit from the standard

A verdict used to carry the limit it was judged against as a constructor
field. In 3.3.0 three did: `ToneAssessment.criterion_db`,
`ExposureAssessment.action_value` and `limit_value`, and
`RigidMassCalibrationResult.tolerance`. Six more that are newer than 3.3.0
did in 4.0.0rc1, and the rest of the table arrived after 4.0.0rc1. Anything
that built one by hand, or rewrote one with `dataclasses.replace`, could
judge a measurement against any number and still print the standard's name
over the result. In 4.0 every limit a standard prints is a read-only
property, read from the fields that select it: the bands, the condition, the
source, the class, the room. A verdict that was stored beside its limit is
read from the measured fields too, or checked against them when the result
is built, so it cannot contradict the limit. The functions that return these
verdicts take the same arguments and give the same answers, and every name
below, in its 4.0 spelling, still reads the same value; only code that constructs a verdict
directly, or replaces one of these fields, has to change. The last column
says where each verdict first shipped.

| Verdict | No longer constructor fields | Fields it keeps or gains | Since |
| --- | --- | --- | --- |
| `building.PositionSpreadCheck` | `limit_db`, `stage`, `spread_db`, `action`, `next_positions`, `corner_standard_deviation_db` | `levels`, which all of them are read from | after 4.0.0rc1 |
| `building.HeavyImpactSourceCheck` | `frequencies`, `nominal`, `tolerance_db`, `deviation`, `within_tolerance`, `passes` | `source`, `measured` | 4.0.0rc1 |
| `noise_control.BandFlatnessCheck` | `limit_db`, `within_limit`, `passes` | `octave_frequencies`, `spread_db` | after 4.0.0rc1 |
| `noise_control.SourcePositionCheck` | `n_required_positions`, `passes`, `exceeds_max` | `n_positions_used`, `max_octave_spread_db` | after 4.0.0rc1 |
| `noise_control.EnclosureTestEnvironmentCheck` | `environmental_correction_limit_db`, `background_margin_limit_db`, `required_area_ratio`, `passes` | `base_standard`, `actual_area_ratio`, `mean_absorption_coefficient` | after 4.0.0rc1 |
| `environment.ReflectionGridCheck` | `nominal_m`, `deviations_m`, `within` | `check`, `path_differences_m` | after 4.0.0rc1 |
| `emission.HardWalledRoomCheck` | `limit_db`, `min_volume_m3`, `box_dimension_limit_m`, `min_microphone_distance_m` | the bands, the room and the box | after 4.0.0rc1 |
| `emission.ReferenceSoundSourceVerdict` | every `*_limit_db`, `adjacent_step_db`, `core_range_db`, `extended_range_db`, `frequency_range_met`, `not_judged` | the bands, the levels and the measured figures | after 4.0.0rc1 |
| `emission.ReferenceSourceDriftResult`, `emission.SpecialRoomSuitabilityCheck` | `limit_db` | the bands | after 4.0.0rc1 |
| `emission.SpecialRoomReverberationCheck` | `lower_limit`, `upper_limit` | the bands | after 4.0.0rc1 |
| `emission.IntensityInstrumentComplianceResult` | `limit_class1`, `limit_class2`, `spacing_offset_db` | `device`, `spacing_m`; the band rows are read from them, see the next section | 4.0.0rc1 |
| `emission.InverseSquareLawResult`, `emission.SourceDirectionalityResult` | `tolerance_db` | `room` selects it; the qualified radii must be the ones the levels reach | after 4.0.0rc1 |
| `hearing.AmbientNoiseCheck` | `limits_db`, `table_bands_hz` | gains `earphone_attenuation` and `allowed_threshold_shift_db` | after 4.0.0rc1 |
| `hearing.FixtureIsolationVerification` | `min_isolation` | the bands | after 4.0.0rc1 |
| `hearing.REATSoundFieldCheck` | `allowable_variation_db` | gains `free_field_rejection` | after 4.0.0rc1 |
| `hearing.DiffuseSoundFieldCheck` | `allowable_variation_db` | gains `front_to_random_index` | after 4.0.0rc1 |
| `hearing.FreeSoundFieldCheck` | `axis_offset_m`, `inverse_distance_difference` | `field` and `loudspeaker_distance_m` select them | after 4.0.0rc1 |
| `electroacoustics.ProgramSignalCheck` | `offset_db`, `relative_levels`, `lower_tolerance_db`, `upper_tolerance_db` | `frequencies`, `band_levels` | after 4.0.0rc1 |
| `electroacoustics.NeckLoopVerification` | `limits` | `neck_loop_type` selects it | after 4.0.0rc1 |
| `psychoacoustics.ToneAssessment` | `prominence_limit_db`, `prominent` | gains `method`, `"tone_to_noise_ratio"` or `"prominence_ratio"` | 3.3.0 |
| `underwater.WeightedExposureResult` | `criteria` | gains `impulsive` | 4.0.0rc1 |
| `vibration.ExposureAssessment` | `action_value`, `limit_value`, `exceeds_action`, `exceeds_limit`, `zone` | `value`, `kind`, `metric` | 3.3.0 |
| `vibration.PhaseVerification`, `vibration.WeightingVerification` | `tolerance_deg` (phase), `within_tolerance` | the weighting and the frequencies | 4.0.0rc1 |
| `vibration.RunningRMSDecayVerification` | `printed_time_s`, `tolerance_s` | `method`, `integration_time`, `measured_time_s` | after 4.0.0rc1 |
| `vibration.SignalBurstVerification` | `printed`, `deviation_percent`, `tolerance_percent`, `within_tolerance` | the table row, the columns and `measured` | 4.0.0rc1 |
| `vibration.VibrationMeterVerification` | `lower_percent`, `upper_percent`, `within_tolerance` | gains `measured_response` | after 4.0.0rc1 |
| `vibration.AssessmentVelocity` | `guide_value_mm_s` | `building_class` selects it | after 4.0.0rc1 |
| `vibration.MountingCheck` | `passes`, `frequency_limit_hz`, `peak_acceleration_limit_m_s2`, `device` | gains `peak_acceleration_m_s2` and `upper_frequency_hz` | after 4.0.0rc1 |
| `vibration.DamageAssessment` | `guideline_mm_s` | gains `massive_structure`, by name only | 4.0.0rc1 |
| `vibration.RigidMassCalibrationResult` | `expected`, `relative_deviation`, `within_tolerance`, `passes`, `relative_tolerance` | `frequencies`, `measured`, `mass`, `quantity` | 3.3.0 |
| `vibration.LevelDifferenceCheck` | `limit_db` | `condition` selects it | after 4.0.0rc1 |
| `vibration.OutputMassCheck` | `mass_limit_kg` | gains `output_apparent_mass_kg`, the measured output force over output acceleration | after 4.0.0rc1 |

Two calls change too. `rigid_mass_calibration_check`, now
`verify_rigid_mass_calibration`, no longer takes `tolerance`: ISO 7626-2:2015 7.5.2 says the block "shall agree within ±5 %",
so a tighter in-house acceptance is read from `.relative_deviation` instead. And
`HeavyImpactSourceCheck` and `RigidMassCalibrationResult`, whose `passes` was a
stored field, refuse to be read as a truth value like every other verdict, so
`if check:` raises `TypeError` and the verdict is `.passes`.

```python
import dataclasses

from phonometry import vibration

check = vibration.check_blocked_output(frequencies=[100.0, 200.0], input_acceleration_level=[90.0, 95.0], output_acceleration_level=[60.0, 70.0])
print(check.limit_db, check.passes)
# 20.0 True
try:
    dataclasses.replace(check, limit_db=10.0)
except TypeError as error:
    print(type(error).__name__)
# TypeError
calibration = vibration.verify_rigid_mass_calibration([0.104, 0.093], frequencies=[50.0, 500.0], mass=10.0)
print(calibration.relative_tolerance, calibration.within_tolerance.tolist())
# 0.05 [True, False]
```

The limits a standard leaves to the user stay fields: the "default" roughness
and decay-rate limits of ISO 3095, the tolerance ISO/DIS 16032 7.6 does not
print for "approximately 30 s", the curing period a product specification
sets under ISO 10140-1 G.4, the threshold shift ISO 8253-1 lets the tester
accept, and the specification limits, test-case limits and limit rows the
caller passes to the conformance, ISO 17534-1 and RD 1367/2007 checks. The
requirement records of ISO 8297 and IEC 60118-4, `PlantRequirement` and
`LoopRequirement`, also keep each row's limit as a field: one record type
holds requirements whose limits mix printed figures with the plant's geometry,
the specified field strength or the noise measured with the loop off.

## A verdict is read from the values it holds

The section above took the printed limits out of the constructors. The verdict
flags stayed in: `passes`, `qualified`, every `*_met` and `*_ok`,
the advisories, and the class of each band of a filter, weighting or intensity
instrument verdict. The function that built a result worked them out and
stored them beside the readings they came from, so a result built by hand, or
rewritten with `dataclasses.replace`, could hold readings that fail and a flag
that says they pass. In 4.0 every one of them is a read-only property, read
from the values the result holds and the limit the standard prints. A result
keeps what its verdict is read from: the readings, the margins, the positions,
the measured figures. A figure that only fed the verdict, such as the rounded
level of an RD 1367/2007 period or the share of raindrops inside their
tolerance, is a property too. The functions that return these results take the
same arguments and return the same verdicts, and every name in the table still
reads the same value; only code that builds one of these results directly, or
replaces one of the listed fields, has to change. "By name only" marks a field
that is keyword-only.

| Result | No longer constructor fields | Read from | Since |
| --- | --- | --- | --- |
| `building.JointTestElementCheck` | `length_ok`, `width_ok`, `passes` | `joint_length_m`, `joint_width_mm`, `window_or_door_gap` | after 4.0.0rc1 |
| `building.GapWidthCheck` | `gap_width_mm`, `spread_mm`, `enough_positions`, `uniform`, `passes` | `readings_mm` | after 4.0.0rc1 |
| `building.JointGapSeriesCheck` | `nominal_measured`, `min_measured`, `working_range_measured`, `passes` | `gap_widths_mm`, `nominal_gap_mm`, `min_gap_mm` | after 4.0.0rc1 |
| `building.LiningCuringCheck` | `cured`, `lag_within_third`, `passes` | `curing_time_days`, `time_lag_days`, `required_curing_days` | after 4.0.0rc1 |
| `building.RainGeneratorVerification` | `rate_deviation_mm_h`, `rate_ok`, `drop_share`, `drops_ok`, `velocity_share`, `velocities_ok`, `passes` | `rain_type`, `rainfall_rate_mm_h`, `drop_diameters_mm`, `fall_velocities_m_s` | after 4.0.0rc1 |
| `building.ServiceEquipmentPositionCheck` | `separation_m`, `surface_distance_m`, `source_distance_m`, `heights_m`, `corner_height_m`, `corner_wall_distances_m` and the six `*_ok` | the room, the corner and the positions | after 4.0.0rc1 |
| `building.DBHRCheck` | `reported`, `margin`, `passes` | `requirement`, `value` | 4.0.0rc1 |
| `building.LowFrequencyIntensityResult`, `building.LowFrequencyElementResult` | `qualified` | `surface_pressure_intensity_indicator`, against the 6.4.2 limit `absorbing_specimen_surface` selects | 4.0.0rc1 |
| `electroacoustics.BackgroundNoiseAssessment` | `reference_signal_to_noise_ratio_db`, `category`, `report_required` | `noise_levels`, `noise_is_tonal` | after 4.0.0rc1 |
| `electroacoustics.FeedbackStabilityResult` | `is_stable` | `loop_gain`, `stability_margin` | 4.0.0rc1 |
| `emission.FreeFieldCheck` | `room`, `frequencies`, `band_radius_m`, `max_qualified_radius_m`, every `*_met`, `full_frequency_range`, `conforming_range_hz`, `conforming_radius_m`, `not_judged` | the arguments of `check_free_field`: gains `source_directionality`, `reflecting_plane_absorption_coefficient`, `reflecting_plane_margin_m`, `paths_in_working_area`, `speed_of_sound` | after 4.0.0rc1 |
| `emission.IntensityInstrumentComplianceResult` | `bands`, `overall_class`, `range_limited` | `frequencies`, `residual_index`, `device`, `spacing_m` | 4.0.0rc1 |
| `emission.ReferenceSourceCalibration` | `sound_power_level`, `intensity_bands`, `intensity_agreement`, `room_qualified` | gains `intensity_sound_power_level` and `room_qualification` | after 4.0.0rc1 |
| `emission.HardWalledSoundPowerResult` | `background_requirement_met`, `upper_bound` | gains `background_margin_db`, `reference_background_margin_db` | after 4.0.0rc1 |
| `emission.InSituSoundPowerResult` | `background_requirement_met`, `upper_bound`, `grade`, `sigma_r0`, `sigma_tot`, `expanded_uncertainty` | gains `background_margin_db`, `reference_background_margin_db`, the smallest over the positions, and `excess_levels`, `directivity_range_db`, the two indicators Table 2 grades by | 4.0.0rc1 |
| `emission.SpecialRoomSoundPowerResult` | `background_requirement_met`, `background_requirement_met_a` | gains `background_margin_db`, `reference_background_margin_db`, `background_margin_a_db` | after 4.0.0rc1 |
| `emission.EmissionPressureResult` | `upper_bound` | gains `background_margin_db`, by name only | 4.0.0rc1 |
| `emission.PrecisionCriteria` | `criterion_1` to `criterion_5`, `qualified` | gains the readings: `indicators`, `scan_intensity_level_1`, `scan_intensity_level_2`, `frequencies`, `repeatability_limit_db`, `pressure_residual_index`, `field_nonuniformity_1`, `field_nonuniformity_2` | 3.3.0 |
| `emission.DiscretePointIntensityResult` | everything but the indicators and the grade: `partial_power`, `sound_power`, `sound_power_level`, `achieved_grade`, both criteria, the A-weighted figures and the rest | gains `normal_intensity`, `segment_areas_m2`, `pressure_residual_index`, `fraction` | 4.0.0rc1 |
| `emission.TurbineTestEnvironmentCheck` | `correction_ok`, `wind_ok`, `windscreen_advised` | `environmental_correction`, `ratio`, `wind_speed_m_s` | after 4.0.0rc1 |
| `environment.ImpulseOnset` | `level_difference`, `prominence`, `qualifies` | `level_start`, `level_end`, `onset_rate` | 3.3.0 |
| `environment.ImpulseProminenceResult` | `per_impulse`, `qualifies`, `prominence`, `adjustment` | `onset_rates`, `level_differences`, `assessment_period_minutes` | 3.3.0 |
| `environment.ResidualCorrectionResult` | `reliable` | `margin` | 3.3.0 |
| `environment.PeriodAssessment` | `reported_level`, `reported_long_term`, `max_phase_level`, `phase_pass`, `daily_pass`, `long_term_pass` | `phases`, the two levels and `limit`; gains `new_activity`, by name only | 4.0.0rc1 |
| `environment.ModulationPeriod` | `modulation_depths_db`, `fundamental_frequencies_hz`, `n_valid_blocks`, `rated`, `rating_db`, `mean_modulation_frequency_hz`, `mode_modulation_frequency_hz` | `blocks` | after 4.0.0rc1 |
| `environment.SoundRelevantTurbines` | `relevant`, `total_level`, `relevant_level` | `predicted_levels` | after 4.0.0rc1 |
| `environment.WindShearProfile` | `typical` | `shear_exponent` | after 4.0.0rc1 |
| `environment.WindTurbineTonalityResult` | `is_audible` | `tonal_audibility`, `has_identified_tone`, itself read-only (next section) | 3.3.0 |
| `filters.FilterComplianceResult` | `bands`, `overall_class`, `range_limited` | gains `band_margins`, the rows without their class | 3.3.0 |
| `filters.WeightingComplianceResult` | `bands`, `overall_class`, `range_limited` | gains `band_margins`, the rows without their class | 4.0.0rc1 |
| `hearing.AscendingThresholdResult` | `threshold_level`, `determined`, `series_exhausted` | `ascent_levels`, `shortened` | after 4.0.0rc1 |
| `hearing.TaskContribution` | `spread_advisory` | `n_samples`, `sample_range_db` | 3.3.0 |
| `hearing.ExposureResult` | `sampling_advisory` | gains `sample_range_db`, `n_workers`, `sample_duration_hours`, by name only | 3.3.0 |
| `hearing.AttenuationDifferenceResult` | `difference`, `significance_limit_db`, `significant` | the two means and their expanded uncertainties | after 4.0.0rc1 |
| `materials.CeilingSpecimenCheck` | `area_error_m2`, `deflection_ok`, `substructure_ok`, `fixture_ok`, `supports_ok`, `humidity_ok`, `ce_marking_depth`, `passes` | gains the measured figures: `deflection_mm`, `substructure_width_mm`, `substructure_height_mm`, `fixture_density_kg_m2`, `support_width_mm`, `support_height_mm`, `support_center_distance_m`, `lowest_relative_humidity_percent` | after 4.0.0rc1 |
| `metrology.TrendTestResult` | `trend_free`, `bounds` | `statistic`, against the region `values`, `method`, `alpha` and `median` give | 3.3.0 |
| `metrology.StationarityTestResult` | `stationary`, `bounds` | `trend_statistic`, against the region `segment_values`, `method` and `alpha` give | 3.3.0 |
| `metrology.CouplerCheck` | `ratio_recommended`, `approximation_valid`, `full_solution_advised`, `conditions_valid` | gains `heat_conduction_method`, `temperature_c`, `static_pressure_pa`, `relative_humidity_percent`, `in_air`, by name only | after 4.0.0rc1 |
| `metrology.FreeFieldArrangementCheck` | `distances_ok`, `support_ok`, `annex_a_range`, `attenuation_accuracy` | gains `air_attenuation` | after 4.0.0rc1 |
| `noise_control.CabinUncertainty` | `ratio_satisfied`, `stateable`, `stated_band_range_hz`, `increased_uncertainty_band_range_hz`, `excess_standard_deviation_db` | `method`, `volume_ratio` | after 4.0.0rc1 |
| `room.RoomAcousticsResult` | `edt_valid`, `t20_valid`, `t30_valid` | `dynamic_range` and the decay times | 3.3.0 |
| `room.BackgroundMarginCheck` | `needs_correction`, `unusable`, `passes` | `margins_db` | after 4.0.0rc1 |
| `room.PredictionDetailCheck` | `passes`, `room_ok`, `fittings_ok`, `sources_ok` | gains `room_detail`, `fitting_detail`, `source_detail` | after 4.0.0rc1 |
| `underwater.WeightedExposureResult` | `exceeds_injury`, `exceeds_tts` | `sel_margin`, `peak_margin`, `tts_margin`, `tts_peak_margin` | 4.0.0rc1 |
| `vibration.PeopleAssessment` | `passes`, `criterion`, `within_uncertainty` | `kb_fmax`, `kb_ftr`, `guide`, `source`; gains `rare_short_events`, by name only | after 4.0.0rc1 |
| `vibration.RailwayChange` | `passes`, `kb_fmax_met`, `kb_ftr_met`, `kb_fmax_increase_percent`, `kb_ftr_increase_percent` | gains `kb_fmax_before`, `kb_fmax_after`, `kb_ftr_before`, `kb_ftr_after` | after 4.0.0rc1 |
| `vibration.TransferStiffnessResult` | `valid` | gains `transmissibility`, \|T\| of the indirect method | 3.3.0 |
| `vibration.DrivingPointStiffnessResult` | `adequate` | gains `blocked_output_difference`, `unwanted_input_difference` | after 4.0.0rc1 |
| `aircraft.AircraftSystemComplianceResult` | `passes`, `checks` | gains `directional`, `frequency_response`, `linearity`, `resolution`, the arguments of `verify_aircraft_noise_system` | 4.0.0rc1 |
| `broadcast.QuasiPeakDynamicsResult` | `passes`, `worst_margin_db`, `worst_deviation_db`, `stimuli` | gains `readings_percent`, the eleven readings in the order of Tables 2 and 3 | 4.0.0rc1 |
| `building.FloorCoveringImprovementResult` | `limited` | gains `background_margin_db`, the smallest margin over the positions and both floors | 3.1.0 |
| `building.VibrationReductionResult` | `single_number`, `bracketed` | `frequencies`, `k_ij`; gains `modal_overlap`, `fraction` | 3.1.0 |
| `building.ServiceEquipmentBackgroundResult` | `difference`, `correction`, `corrected_levels`, `regime` | `measured_levels`, `background_levels` | after 4.0.0rc1 |
| `building.ServiceEquipmentResult` | `standardizable` | `frequencies`, `fraction` | after 4.0.0rc1 |
| `emission.SoundPowerIntensityResult` | `partial_power_level`, `sound_power`, `sound_power_level`, `negative_band`, `negative_partial_power_index`, `dynamic_capability_index`, `achieved_grade`, `a_weighting_omitted_bands`, `sound_power_level_a` | `partial_power` and the indicators; gains `pressure_residual_index`, `fraction`, `repeatability_limit_db` | 3.1.0 |
| `emission.PrecisionIntensityResult` | `sound_power`, `sound_power_level`, `sound_power_level_normalized`, `not_applicable_band`, `sound_power_level_a` | `partial_power`; gains `temperature_c`, `static_pressure_pa`, by name only | 3.1.0 |
| `emission.InDuctSoundPowerResult` | `information_only_band` | `frequencies`, `flow_velocity` | 4.0.0rc1 |
| `emission.SourceLocationPlan` | `spectral_character`, `a_weighted_spectral_character` | `standard`, `standard_deviation_db`, `a_weighted_standard_deviation_db` | after 4.0.0rc1 |
| `environment.ImpulsiveSoundResult` | `prominence`, `adjustment`, `category`, `adjusted_laeq` | `onsets`, `laeq` | 3.3.0 |
| `environment.ModulationBlock` | `status` | `prominence`; gains `excluded`, by name only | after 4.0.0rc1 |
| `environment.ReferenceTrackCheck` | `conditions` | the roughness, the decay rates and the limits; gains `curve_radius_m`, `track_gradient_ratio`, by name only | after 4.0.0rc1 |

`FilterComplianceResult` and `WeightingComplianceResult` hold their per-band
rows as `band_margins`: the rows `bands` held, without the `"class"` key. A
row that states a class is refused, and the `bands` property adds to each row
the class its margins earn, so `result.bands[i]["class"]` reads as before.
`IntensityInstrumentComplianceResult` takes no band rows at all: it holds the
frequencies and the measured pressure-residual intensity index, and reads the
rows, the class and `range_limited` from them, the device and the microphone
separation.

The rows a verdict is read from are read-only. `band_margins` and
`between_nominals` are copied into read-only mappings when the result is
built, so a write into one raises `TypeError` and a later write into the
dictionaries you built it from does not move the class; copy a row with
`dict(row)` to change it, since `copy.deepcopy` cannot copy a read-only
mapping. The rows of `AircraftSystemComplianceResult.checks`,
`QuasiPeakDynamicsResult.stimuli` and `ReferenceTrackCheck.conditions` are
built from what the result holds and the tables of the standard each time
they are read.

```python
import dataclasses

from phonometry import building, filters

gap = building.check_gap_width([5.0, 5.1, 5.2, 5.1])
print(gap.passes, round(gap.spread_mm, 1))
# True 0.2
try:
    dataclasses.replace(gap, passes=False)
except TypeError as error:
    print(type(error).__name__)
# TypeError
wider = dataclasses.replace(gap, readings_mm=(5.0, 5.1, 5.6, 5.1))
print(wider.uniform, wider.passes)
# False False
bank = filters.OctaveFilterBank(fs=48000, fraction=1, order=6, limits=[125, 4000])
result = filters.verify_filter_class(bank)
print(result.overall_class, result.bands[0]["class"], "class" in result.band_margins[0])
# 1 1 False
```

A flag stays a field where it is no verdict against a limit and nothing the
result holds decides it: an option the caller sets, such as `small_room` or
`noise_is_tonal`; a branch the caller chose by what they gave, such as
`InverseSquareLawResult.origin_fitted`; a fact of an input the result does not
keep, such as `TimeWeightedEnvelope.calibrated`; a property of the file read;
whether an iterative solver converged; and a column of a published table row.
`CriticalCouplingResult.converged` keeps the outcome of its solve, which the
result cannot run again, but it can no longer claim convergence beside an
absorption that does not exceed 0.999, the third condition of the flag.
A regime the result could read from its own values is a verdict, and the next
section lists the ones that moved. `PlantRequirement` and `LoopRequirement` do not change: their rows
keep each limit as a field for the reason the section above gives, and
`PlantRequirement.holds` stays beside it. `TrackCondition` keeps its `holds`
as a row of the report, but `ReferenceTrackCheck` builds its conditions from
the track it holds, so no verdict reads one built elsewhere. The yes/no
`checks` of `SoundLevelMeterPeriodicRequirement` stay as well: they are what
the tester saw, an overload indicated or an indicator latched, not a limit
judged.

## A result reads its regime from the values it holds

Some results stored a regime or a classification beside the values it was
read from: the regime of a valve, whether a hammer rebounds, whether terrain
screens a path, whether a tone was found, whether a synchronous average had to
interpolate. The function compared values the result holds, or could hold,
with a constant or a threshold its source prints, and stored the answer, so a
result built by hand could hold the stiffness of an under-critical hammer and
say it is over-critical. In 4.0 each of them is a read-only property, read
from the values the result keeps, and a result that did not keep what the test
reads now keeps it, with the unit in the name. "By name only" marks a field
that is keyword-only.

A value exactly on a boundary falls where the source puts it. Hopkins prints
the over-critical case as K m ≥ 4 Zdp², so critical damping is over-critical,
and IEC TS 61400-11-2 asks for a total "at least 3 dB" above the background
before the logarithmic subtraction, so a difference of 3 dB takes it.
IEC 60534-8-4 does not settle its cavitation threshold one way: the test of
5.1 leaves the threshold itself to neither side, the region of Equation (9)
and Equation (19b) put it with the cavitating points, and 4.1, Equation (18b)
and 6.3 with the turbulent ones. The library reads it as turbulent, where
Equation (9) returns zero and the two branches meet without a step.

The functions take the same arguments and return the same numbers. Code that
builds one of these results directly, or replaces one of the fields its regime
is read from, has to change, and so does code that reads `fraction` from
`vibration_reduction_index` (see below the table).

| Result | No longer a constructor field | Read from | Since |
| --- | --- | --- | --- |
| `building.TappingForceResult` | `over_critical`, K m ≥ 4 Zdp² (Hopkins Eq. 3.95) | `contact_stiffness`, `impedance`; gains `mass`, by name only | 4.0.0rc1 |
| `noise_control.HydrodynamicValveNoise` | `regime`, cavitating when Δp exceeds x_Fzp1 (p1 - pv) (IEC 60534-8-4 5.1) | `differential`, `corrected_ratio`; gains `inlet_pressure_pa`, `vapor_pressure_pa` | 4.0.0rc1 |
| `noise_control.AerodynamicValveNoise` | `regime`, the five intervals of IEC 60534-8-3 5.2 | `pressure_ratio`, `boundaries`; gains `specific_heat_ratio`, `pressure_recovery`, `efficiency_correction`, by name only | 4.0.0rc1 |
| `aircraft.TerrainScreeningResult` | `screened`, terrain strictly above the line of sight | `source`, `receiver`, `distances_m`, `heights_m` | 3.3.0 |
| `hearing.AutomaticThresholdResult` | `is_peak`, `retained` (ISO 8253-1 6.3.5 a)) | `reversal_levels` | after 4.0.0rc1 |
| `hearing.SweepThresholdResult` | `is_peak` | `reversal_levels` | after 4.0.0rc1 |
| `metrology.WaveMotionCorrection` | `interpolated` | `frequencies`, `speed_of_sound_ratio` | after 4.0.0rc1 |
| `noise_control.CabinInsulationResult` | `apparent` (ISO 11957 3.6) | `method` | after 4.0.0rc1 |
| `noise_control.WeightedCabinInsulation` | `apparent` (ISO 11957 3.9) | `method`, which `weighted_cabin_insulation` now takes as `cabin_insulation` does | after 4.0.0rc1 |
| `environment.WindTurbineTonalityResult` | `has_identified_tone` (IEC 61400-11 9.5.2 to 9.5.4) | `levels`, `frequencies`; gains `candidate_frequency_hz`, by name only | 3.3.0 |
| `building.LaboratoryJointInsulationResult` | `regime` (ISO 10140-1 J.1) | `r_s_prime`, `r_s_max`; gains `limit_at_max`, by name only | after 4.0.0rc1 |
| `environment.TurbineSoundLevels` | `regimes` (IEC TS 61400-11-2 11.7) | `total_levels`, `background_levels` | after 4.0.0rc1 |
| `underwater.WestonPropagationResult` | `regime` | `range_m`, `boundaries` | 4.0.0rc1 |
| `signals.SynchronousAverageResult` | `interpolated`, f_s T not a whole number of samples | `fs`, `period_s` | 4.0.0rc1 |

`building.VibrationReductionResult.fraction` is a field, the band set the
caller states: `octave_bands()` states `fraction=1`, since a single octave band
cannot be told from a one-third-octave band by its spacing.
`vibration_reduction_index` no longer fills it with the band set it read from
the frequencies; it leaves `None`, and the result reads the spacing each time
it takes the Annex A mean, which gives the same mean as before.

The numbers a regime selects are held to it, so a result built by hand can no
longer carry one regime beside the values of another. When it is built, each
of these results refuses:

- `TappingForceResult`: a cut-off frequency, a limiting frequency, a force
  spectrum or a power input that is not what K, Zdp and m give in their
  regime, and limits of Eqs. (3.99) and (3.100) that are not a factor of 2
  apart.
- `HydrodynamicValveNoise`: a vapour pressure at or above the inlet pressure;
  an x_F or an x_Fzp1 that is not what Equation (1) or (3c) gives from the
  fields beside it; a point at or past flashing, x_F = 1; cavitation fields on
  a turbulent point, or none on a cavitating one.
- `AerodynamicValveNoise`: boundaries that are not those of its gas and its
  trim, and a Mach number or an acoustical efficiency of another regime.
- `TerrainScreeningResult`: a source or a receiver that is not a finite point,
  a source at or past the receiver, a section that does not run from one to
  the other, and a path difference or diffracting edges that are not those
  of the rubber band over that section.
- `AutomaticThresholdResult` and `SweepThresholdResult`: reversals that do not
  alternate, a tracing that keeps no peak or no valley, and a mean, a
  threshold or a running threshold that is not what the reversals give.
- `WaveMotionCorrection`: a frequency beyond the last row of Table C.3, and a
  correction the table does not give at its frequency.
- `CabinInsulationResult`: an A-weighted insulation under any method but the
  actual noise.
- `WindTurbineTonalityResult`: a candidate that is not a line of the spectrum
  at or above 20 Hz, and a Formula 30 to 34 chain that is not the one the
  spectrum gives about it.
- `LaboratoryJointInsulationResult`: a corrected index of another rule of J.1.
- `TurbineSoundLevels`: a level difference other than the total less the
  background, a turbine level of another rule of 11.7, and an uncertainty on
  a bin whose level cannot be determined.
- `WestonPropagationResult`: a composite loss that is not the law of the
  regime in force.
- `SynchronousAverageResult`: a period grid other than `round(fs * period_s)`
  samples.

```python
import dataclasses

import numpy as np

from phonometry import building

bands = np.array([100.0, 200.0, 400.0, 800.0])
force = building.tapping_force_spectrum(bands, 1.0e6, 3.0e4)
print(force.over_critical)
# False
print(building.tapping_force_spectrum(bands, 1.0e6, 100.0).over_critical)
# True
try:
    dataclasses.replace(force, impedance=100.0)
except ValueError as error:
    print("cut_off_frequency" in str(error))
# True
```

## A wrong type raises `TypeError`, a missing key `KeyError`, and every warning has a topic

The Python documentation draws the line between the two refusals:
`TypeError` is "raised when an operation or function is applied to an object
of inappropriate type", and `ValueError` "when an operation or function
receives an argument that has the right type but an inappropriate value". In
3.3.0 and 4.0.0rc1 seventy-six refusals asked an argument for its type and
raised `ValueError`, thirty-two more caught a `TypeError` and raised it again
as a `ValueError`, and the shared guards of every scalar parameter refused an
array that way too, while a handful of others raised `TypeError` for the same
mistake. 4.0 raises `TypeError` for a wrong type and `ValueError` for a
right type with a wrong value, everywhere. A call wrapped in `except
ValueError` to absorb any bad input should catch `(TypeError, ValueError)`.

| Passed | 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| an array, `None`, a text or an object that is not a number where one number belongs, on any scalar parameter | `ValueError`, and a text that reads as a number, such as `"20"`, was taken as that number | `TypeError`, naming the parameter, for `"20"` and `"fifty"` alike: a text is the wrong type where a number belongs, whatever it reads as |
| an element that is not a number inside an array of numbers (`[None, 1.0]`, `["94.0", "94.1"]`, a `bytearray` in an array of objects) | `ValueError`, and text numpy reads as numbers was taken as them | `TypeError`, for text whatever it reads as |
| a text in any form but a `str` (a `bytes`, a `bytearray`, a text or a `bytearray` in a sequence or an array), `None` where it is no option, or an object that is no number, where a choice beside numbers takes its numbers: `termination=` of `materials.layered_absorber` and `materials.diffuse_field_absorption`, `initial_state=` of `filters.time_weighting`, `coefficients=` of `materials.delany_bazley`, `target=` of `room.shaped_sweep_signal`, `flow_resistivity=` of `aircraft.terrain_screening_adjustment` and `aircraft.RotorcraftGround`, `speech_spectrum=` of `speech.speech_intelligibility_index` | a text that read as a number was taken as it (`termination=["400", "400"]` as an impedance of 400 Pa s/m, `coefficients=b"12345678"` as the codes of its eight characters, `speech_spectrum=["60"] * 18` as eighteen levels of 60 dB), and the rest failed with an error that named nothing, `None` was read as `nan`, or the record stored it | `TypeError`, naming the parameter and its options; `RotorcraftGround` refuses it when built. Write the option as a `str` (`"rigid"`) and the numbers as numbers (`[400.0, 400.0]`) |
| a ragged nesting as `initial_state=` of `filters.time_weighting` | `TypeError` | `ValueError`, naming the parameter, as for the `termination=` of `materials.layered_absorber` |
| a `target=` of `room.shaped_sweep_signal` that holds other than two arrays | the arrays after the second were left unread | `ValueError`, naming the parameter, when the call starts |
| a complex number or array where a real one belongs, on any parameter the shared guards read, `initial_state=` of `filters.time_weighting` included, an array of objects that holds a NumPy complex number among them; such an array among the scale values or the correlated variables of the soundscape functions of `environment`, and a complex position of `environment.method_a_scale_values` | `ValueError`, and a complex state, such an array and a NumPy complex position were read as their real part with no more than a `ComplexWarning` | `TypeError`, saying it must be real |
| a NumPy complex number where one real number belongs (`np.complex128(343 + 50j)`), on any parameter the shared guards read, or inside an array of objects; a complex value or a text on a real input of the FDTD engines: a map of `simulation.FDTD2D` or `simulation.ElasticFDTD2D` (`c`, `rho`, `c_p`, `c_s`, `damping`), `dx`, `cfl`, the numbers of the sources and of `simulation.Material`, `simulation.ContourProbe`, `simulation.ContourPhasors` and `simulation.far_field_from_contour`; anything but one real number (a complex number, a text, `None`, a list or an array, a `bytearray` among them) as the time `t` of the `value(t)` of `simulation.GaussianPulse`, `CWSource` and `SignalSource`, or as a sample a source's waveform returns as an engine steps | read as its real part with no more than a `ComplexWarning`: the elastic engine stepped the real part of a complex `c_p`, `c_s` or `rho`, or of a complex sample of an `ExplosionSource` or a `ForceSource`, a `PlaneWaveSource` failed on one with NumPy's casting error, every map of both engines took a text as the number it spells (`c="343"`), and `None`, a list or an array as a time or a sample failed with an error of Python's or NumPy's that named nothing | `TypeError`, saying it must be real, that it must be numbers and not text, or that it must be one real number |
| a complex value, a text or a `bytearray` among the numbers of any parameter that takes numbers (a spectrum, a frequency axis, a signal, a field of a record, a reflection factor or an impedance), and a complex number of either kind where one number belongs, on any parameter the shared scalar guards read | a NumPy complex number or a complex array was read as its real part with no more than a `ComplexWarning` (`environment.method_b_scale_values(np.complex128(0.5 + 0.3j))` rated the mark at 0.5), while a Python complex, alone or in a list, raised an unnamed `TypeError`; a text was parsed (`["94.0"]` as 94 dB), and a `bytearray` read as the codes of its characters (`[bytearray(b"12")]` as levels of 49 and 50 dB) | `TypeError`, naming the parameter: it must be real, not complex, or numbers, not text; a parameter that takes complex numbers refuses the text only. Take the magnitude or the real part of a complex quantity before the call, and write numbers as numbers |
| a text, a `bytes` or a NumPy complex number given as one number to a parameter its function read with `float()` or `complex()`, or computed with first: `temperature_c=` of `aircraft.npd_atmosphere_increment`, a contribution of `metrology.combined_standard_uncertainty`, the altitude of `aircraft.Aerodrome.pressure_ratio`, the two numbers of `aircraft.MeanGroundPlaneResult.equivalent_height`, `delay=` and `n=` of `materials.in_situ_reflection_factor`, `efficiency_correction` of a `noise_control.AerodynamicValveNoise` you build, and some three hundred more | parsed as the number it spells (`temperature_c="25"` as 25 °C, `[b"12"]` as 12), read as its real part with no more than a `ComplexWarning`, or, computed with first, a `TypeError` of the arithmetic that named nothing | `TypeError`, naming the parameter |
| a number too large for a float: a Python integer such as `10**400`, or a long double or a `Decimal` past a float's largest, as one number or among the numbers of an array | an `OverflowError` from the arithmetic or from NumPy for an integer, and an infinity, with no more than a warning, for a long double or a `Decimal` | `ValueError`, naming the parameter; an infinity you give is still read as one |
| a `collections.UserString`, or a `bytes`, where a pair or a list of labels, names or indices belongs: `shape=` of `simulation.FDTD2D`, `excluded=` of `building.loudest_corner`, `labels=` of `filters.FractionalOctaveBands`, a contribution of `metrology.combined_standard_uncertainty`, a participant's list of `environment.method_b_source_ranking`, `bands=` of `environment.bin_amplitude_modulation`, `ffmpeg_options=` of `io.VideoOptions`, `channel_labels=` of `io.Signal`, a material of `simulation.scholte_speed` and of the elastic engine | measured or split into its characters (a `bytes` into its codes, so `b"car"` ranked the sources `'99'`, `'97'` and `'114'`), and refused as a value of the wrong length or with an error about its nesting, or taken | refused as the text it wraps is, naming the parameter |
| a `collections.UserString`, or a `bytes`, where one name may stand for a list of names: `parameters=` of `environment.binaural_indicators`, `targets=` of `emission.MicrophoneTraverse`, `vocal_efforts=` of `speech.standard_speech_spectra`, `basic_standards=` of `emission.NoiseEmissionDeclaration` | split into its characters, each refused as a name of no row, or kept as a list of characters | refused by the parameter's name as no text, whole |
| a `pathlib.Path` or another path object as the `path` of a result's `.report()` | the fiche was built and then failed with ReportLab's error | the PDF is written there, and `.report()` returns the path as a text |
| an index that is not an integer (a flag, a float, a fraction, a text, or an array of another dtype): `order=` of `signals.miso_coherence`, the channels of `io.Signal.pick` | read through `int()`: `order=(0.5, 1.7)` conditioned the inputs as `(0, 1)` and `order="10"` as `(1, 0)`, `pick([1.5])` picked channel 1 and `pick("01")` channels 0 and 1 | `TypeError`, naming the parameter |
| an array of the wrong kind: a mask that is not boolean (`obstacle_mask=` of `simulation.FDTD2D` and `simulation.fdtd_simulation`, the region masks of `simulation.ElasticFDTD2D.from_regions`, `valid=` of `vibration.band_averaged_stiffness`), `line_counts` of `vibration.BandAveragedStiffness` that are not integers, exclusion flags that are neither booleans nor integers (`excluded_blocks=` of `environment.amplitude_modulation_period`, `excluded=` of `environment.bin_amplitude_modulation`), text where the readings, distances and durations of the service equipment functions of `building` belong (`building.verify_calibration_deviation`, `building.check_background_duration` and the rest) | `ValueError` | `TypeError` |
| a sequence where one measurement belongs: the pressures and temperatures of `noise_control.normal_air_density`, `noise_control.total_pressure`, `noise_control.total_pressure_loss` and `noise_control.pressure_loss_coefficient`, `altitude` of `emission.static_pressure_from_altitude`, `tolerance_s=` of `building.check_background_duration` | `ValueError`, and the `noise_control` functions read a one-element sequence as its element | `TypeError`, a one-element sequence included |
| a whole number (a count, an index, a class, a number of points or of decimals: any parameter written as an `int`) given as a text, a bool or an array: `signals.zoom_fft(..., n_points=)`, `signals.window_metrics(window, n)`, `signals.min_phase(..., oversample=)`, `electroacoustics.swept_sine_distortion(..., n_harmonics=)`, `metrology.stationarity_test(..., n_segments=)`, `vibration.story_fundamental_frequency(n_stories)`, `n_events=` of the sound energy functions and of `emission.SoundEnergyResult` and `emission.ReverberationSoundEnergyResult`, `n=` of `building.prediction_input_uncertainty` and `building.intensity_element_normalized_difference`, `oversample=` of `signals.lc_peak` and `broadcast.true_peak_level`, `max_order=` of `room.image_source_rir` and `room.audible_image_count`, the grid indices and step counts of `simulation.FDTD2D`, `duration_days=` of `vibration.construction_guide_values`, `start_band=` of `aircraft.tone_correction`, `n_level_ranges=` of `metrology.SoundLevelMeterFeatures`, `n_impacts` of `vibration.ImpactMobilityResult`, the position counts of `ReportMetadata` | `ValueError`, or, where the value went through `int()`, a bool taken as 0 or 1, a text parsed and a fraction truncated without a word (`n_points=100.6` drew 100 points) | `TypeError`. A number that is not whole, or is below the least the count can be, is a `ValueError`, and a whole float such as `5.0` is taken as `5` |
| a flag that is not `True` or `False`: `small_room=` of `building.check_service_equipment_positions`, `absorbing_specimen_surface=` of the ISO 15186 insulation, the declarations of the free-field qualification in `emission`, the features of `metrology.SoundLevelMeterFeatures` and the observations of `metrology.SoundLevelMeterPeriodicMeasurements` | `ValueError` | `TypeError` |
| a name that is not a text: the area types, uses and periods of the RD 1367/2007 and DB-HR functions (`environment.activity_limits` and the rest), the Annex A items of `environment.SoundscapeAcousticEnvironment`, the descriptions of `emission.turbine_noise_declaration`, and any choice among named options given as something other than a text (`period=5`) | `ValueError` | `TypeError`; an empty text, or a text that names none of the options, stays a `ValueError` |
| an object of the wrong class: the boxes of `emission.turbine_measurement_surface`, `surface=` of `emission.turbine_microphone_positions`, `correction=` of `emission.check_turbine_test_environment`, the determinations of `emission.turbine_noise_declaration`, the parts of `environment.SoundscapeReport`, a material of the elastic FDTD that is no `Material`, catalogue row or triple, a `waveform` that is not callable, a bare array to `io.write(..., sidecar=True)`, a band calibration where `emission.high_frequency_sound_power_comparison` compares tones | `ValueError` | `TypeError` |
| a text where a sequence belongs, a number where a pair or a list does, or a pair holding an array: `rankings` of `environment.method_b_source_ranking`, `bands=` of `environment.bin_amplitude_modulation`, `exclude_hz=` and the frequency pairs of the ISO 7626-5 mobility, `microphones=` of the IEC 61094-8 corrections, the limits of a filter bank, `shape=` of `simulation.FDTD2D`, the band edges of `electroacoustics.LoudspeakerCharacteristics` and `electroacoustics.MicrophoneCharacteristics` | `ValueError` | `TypeError` |
| a `bytearray` given whole where a pair, a list of labels or of indices, or a sequence of numbers or of arrays belongs: `labels` of `filters.FractionalOctaveBands`, `excluded=` of `building.loudest_corner`, `band_hz=` and the frequency pairs of the ISO 7626-5 mobility, `microphones=` of the IEC 61094-8 corrections, the band edges of `electroacoustics.LoudspeakerCharacteristics` and `electroacoustics.MicrophoneCharacteristics`, the curves of `electroacoustics.LoudspeakerDirectivity`, `MicrophoneDirectivity`, `MicrophoneNoise` and `MicrophoneOverload`, `terrain=` of `aircraft.RotorcraftGround`, `coefficients=` of `materials.delany_bazley`, `shape=` of `simulation.FDTD2D`, `simulation.ElasticFDTD2D` and `simulation.ElasticFDTD2D.from_regions`, `order=` of `signals.miso_coherence`, the channels of `io.Signal.pick`, `low_band_microphones=` of `environment.reflection_index`; and a mapping or a set where those curves, that terrain or those coefficients go | read as the codes of its characters (`labels=bytearray(b"1k")` as the labels `"49"` and `"107"`, `pick(bytearray(b"\x01"))` as channel 1), as the keys of the mapping (`coefficients={0: 1.0, ...}` as C1 to C8 of 0 to 7), or as the members of the set in no order | `TypeError`, naming the parameter |
| a performance of `hearing.assumed_protection_value` or `hearing.hml_rating` that is not a number, a `clause=` of `metrology.max_expanded_uncertainty` that is not a number, a `part=` of `environment.method_a_scale_values` that is a bool | `ValueError` | `TypeError`; a number Table 1 does not tabulate, or a clause or part that does not exist, stays a `ValueError` |

A lookup that misses raises what a mapping raises when the result is read
like one, and `ValueError` when a number falls outside what it covers:

| Asked | 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| `RegulationLimits[period]` for a period it does not hold | `ValueError` | `KeyError`. The key is matched exactly, as a `dict` key is: `limits["Day"]` and `limits[" night "]`, which were read as `"day"` and `"night"`, now raise `KeyError` too. The period of `environment.PeriodAssessment`, a choice, still raises `ValueError` |
| `emission.measurement_positions("hemisphere", ..., n_reflecting_planes=3, grade="survey")` | `NotImplementedError` | the positions 14, 21 and 22 of ISO 3746:2010 Table B.2 |
| `emission.measurement_positions("hemisphere", ..., grade="survey")` over one reflecting plane | positions 4, 5, 6 and 10 of ISO 3744 Table B.1, the array for a source with tones | positions 4, 5, 6 and 10 of ISO 3746:2010 Table B.1, which clause 8.2.1 prescribes: the broadband positions of those numbers in ISO 3744 Table B.2 |
| an `instrument=` Table C.5 does not list (`"Class 1"` for `"class1"`), to `hearing.task_based_exposure`, `hearing.job_based_exposure` and `hearing.full_day_exposure` | `KeyError` | `ValueError`, and `TypeError` for a value that is not text: the instrument is a choice, not a key the caller reads back |
| `fluids.FluidPropertyUnavailable` | the exception | `fluids.FluidPropertyUnavailableError`, still an `AttributeError`, so `hasattr` and `getattr` with a default behave as before |

These warnings now derive from `PhonometryWarning`, each with a topic of its
own, so `warnings.simplefilter("error", phonometry.PhonometryWarning)` reaches
all of them and a filter on the topic reaches one. They are still
`UserWarning`s, so a filter written on that class still matches:

| Emitted by | 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| `environment.sound_absorption_rating` and `environment.sound_reflection_rating` at the 0.99 cap | `environment.RoadDeviceWarning`, a `UserWarning` outside the hierarchy | `environment.RoadDeviceWarning`, a `PhonometryWarning` |
| `building.equivalent_impact_level`, `building.weighted_lining_improvement` and `building.lining_improvement` outside the range their relation is stated for | `UserWarning` | `building.BuildingPredictionWarning` |
| `building.intensity_element_normalized_difference` with `n > 1` | `UserWarning` | `building.LaboratoryInsulationWarning` |
| `room.room_criterion` on a spectrum missing a band from 31.5 Hz to 4000 Hz | `UserWarning` | `room.NoiseCriterionWarning` |
| `aircraft.approach_profile` on a Level-Idle step whose start altitude or start CAS disagrees with the following Level-Idle step (Doc 29 B7.1.4) | `UserWarning` | `aircraft.FlightProfileWarning`, which also reports a following step that is neither Level-Idle nor Descend-Idle (Case 2) |
| `signals.tone_burst` when `fs` and `frequency` are incommensurate | `PhonometryWarning` | `signals.ToneBurstWarning` |
| `underwater.normal_modes`, `underwater.eigenrays` and `underwater.gaussian_beams` | `PhonometryWarning` | `underwater.NumericalPropagationWarning` |
| a filter bank dropping the bands above the Nyquist frequency (`Low sampling rate`) | `PhonometryWarning` | `filters.FilterBankWarning` |

```python
import phonometry
from phonometry import environment, vibration

limits = environment.activity_limits("a")
try:
    limits["noon"]
except KeyError:
    print("KeyError")
for n_stories in ("5", 2.5):
    try:
        vibration.story_fundamental_frequency(n_stories)
    except (TypeError, ValueError) as refusal:
        print(type(refusal).__name__)
print(issubclass(environment.RoadDeviceWarning, phonometry.PhonometryWarning))
# KeyError
# TypeError
# ValueError
# True
```

## A warning names the line of your code that caused it

Every warning of the library is now shown at the first line of the caller's
code, whichever functions of the library it was reached through. Python's
`default` action then shows it once for each line of yours that causes it, and
a filter by module reads your module. A traceback names the warning by the
package that exports it:

| What | 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| the file and line a warning is shown at | the line its `stacklevel` counted to, a line of the library for 33 of them, such as `filters/core.py:698` for every filter bank that dropped a band | the line of your code that made the call |
| `warnings.filterwarnings("ignore", module="phonometry")` | silenced the warnings shown at a line of the library, and no other | silences none; filter by class, `warnings.filterwarnings("ignore", category=phonometry.PhonometryWarning)`, or by topic |
| `warnings.filterwarnings("error", module="my_analysis")` | missed the warnings shown at a line of the library | reaches every warning a call in `my_analysis` causes |
| `filters.OctaveFilterBank(44100)`, `filters.octave_filter(x, 44100)` and the other banks on the default span, at a rate that cannot hold its top bands (44.1, 32, 22.05, 16 or 8 kHz) | `FilterBankWarning: Low sampling rate: frequencies above fs/2 removed` | no warning, and the same bands: the default span is trimmed to what `fs` holds |
| a bank on `limits` you gave that reach past fs/2 | the same warning, at the first call only, since the design is cached | `FilterBankWarning: Low sampling rate: fs = 44100 Hz cannot hold the 20 kHz band, whose upper edge 22387 Hz is above fs/2 = 22050 Hz; it was left out of the bank.`, at every call; a filter on the message `Low sampling rate` still matches |
| a bank at a rate that holds no band of its span, the default one or yours, such as `filters.OctaveFilterBank(20, fraction=3)` | `FilterBankWarning: Low sampling rate: frequencies above fs/2 removed`, and a bank of no band whose analysis came back empty | `ValueError: fs = 20 Hz cannot hold any band from 12.5 Hz to 20 kHz: the upper edge of the lowest, 14.13 Hz, is above fs/2 = 10 Hz.` |
| `vibration.transfer_stiffness_indirect` with a transmissibility that holds `inf` or `nan` | an array holding `-inf+nanj` | `ValueError: 'transmissibility' must contain only finite values.` |
| the name a traceback, a repr or pickle gives the 14 warnings written in private modules, `PhonometryWarning` among them | the private module, `phonometry.fluids._state.FluidAssumptionWarning` | the package that exports it, `phonometry.fluids.FluidAssumptionWarning`; the class is the same, and `inspect.getsource` of it raises `OSError` |

## A choice is matched as it is written

A parameter or a record field typed with a `Literal` of its options, whose
code cleaned the text up before it checked it, now takes the spellings that
`Literal` lists, and only those. Before 4.0, 198 of them folded the case,
stripped the spaces, swapped `_`, `-` and spaces, mapped an alias of their own
or made a text of any value with `str()` before they looked the choice up, so
a call a type checker refused ran all the same:
`filters.WeightingFilter(48000, "a")`, `filters.time_weighting(x, fs,
mode="FAST")`, `vibration.guide_values("residential", edition=1999)`. Two
more read one option and took any other value for the second: the
`onset_rate_method` of `environment.detect_onsets` and
`environment.impulsive_sound_adjustment` fitted anything but `"upper_half"`
as least squares. In 4.0 such a call raises `ValueError`, or `TypeError` for
a value that is not text, and the fix is to write the option as its `Literal`
lists it. The aliases a
`Literal` lists on purpose still work: `"docente"` for `"educational"` in
`building.db_hr_facade_requirement`, `"dnt_w"` for `"r_w"` in
`building.single_number_uncertainty`. Files the library reads, such as an ANP
database, are still read whatever case they write their words in.

```python
from phonometry import filters

try:
    filters.WeightingFilter(48000, "a")
except ValueError as refusal:
    print(type(refusal).__name__)
print(filters.WeightingFilter(48000, "A").weighting)
# ValueError
# A
```

Each row is a parameter that stopped taking a spelling, with an example of each
kind it took and every alias of its own. The examples come from running the
calls the test suite makes, and a few written for the purpose, with the spelling
changed, on the code just before 4.0. Some of the parameters are newer than
4.0.0rc1, or were renamed after it; their rows concern only code written since.

| Parameter | Took before 4.0 | 4.0 raises |
| --- | --- | --- |
| `aircraft.ANPAircraft.event_level(metric=)` | another case (`"EXPOSURE"` for `"exposure"`); spaces around it (`" exposure "` for `"exposure"`) | `ValueError` |
| `aircraft.ANPAircraft.event_level(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPAircraft.noise_contour(metric=)` | another case (`"EXPOSURE"` for `"exposure"`); spaces around it (`" exposure "` for `"exposure"`) | `ValueError` |
| `aircraft.ANPAircraft.noise_contour(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPAircraft.npd_curves(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPAircraft.profile(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPAircraft.revised_npd_curves(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPAircraft.spectral_class(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.event_level(metric=)` | another case (`"EXPOSURE"` for `"exposure"`); spaces around it (`" exposure "` for `"exposure"`) | `ValueError` |
| `aircraft.ANPDatabase.event_level(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.flight_profile(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.noise_contour(metric=)` | another case (`"EXPOSURE"` for `"exposure"`); spaces around it (`" exposure "` for `"exposure"`) | `ValueError` |
| `aircraft.ANPDatabase.noise_contour(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.npd_curves(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" A "` for `"A"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.procedural_profile(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.procedural_steps(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.profile(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.ANPDatabase.revised_npd_curves(operation=)` | another case (`"DEPARTURE"` for `"departure"`); spaces around it (`" departure "` for `"departure"`); aliases of its own (`"a"`, `"approach"`, `"arrivals"`, `"d"`, `"departures"`, `"landing"`, `"take-off"`, `"takeoff"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.AircraftSystemComplianceResult(linearity=)` | keys that are not text but print as options | `TypeError` for a value that is not text |
| `aircraft.PerformanceAircraft.flap(operation=)` | another case (`"d"` for `"D"`); spaces around it (`" D "` for `"D"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `aircraft.engine_installation_correction(mounting=)` | another case (`"WING"` for `"wing"`); spaces around it (`" wing "` for `"wing"`); aliases of its own (`"prop"`) | `ValueError` |
| `aircraft.event_level(metric=)` | another case (`"EXPOSURE"` for `"exposure"`); spaces around it (`" exposure "` for `"exposure"`) | `ValueError` |
| `aircraft.event_level(mounting=)` | another case (`"WING"` for `"wing"`); spaces around it (`" wing "` for `"wing"`) | `ValueError` |
| `aircraft.ground_effect_adjustment(flow_resistivity=)` | another case (`"g"` for `"G"`); spaces around it (`" G "` for `"G"`) | `ValueError` |
| `aircraft.noise_contour(metric=)` | another case (`"EXPOSURE"` for `"exposure"`); spaces around it (`" exposure "` for `"exposure"`) | `ValueError` |
| `aircraft.noise_contour(mounting=)` | another case (`"WING"` for `"wing"`); spaces around it (`" wing "` for `"wing"`) | `ValueError` |
| `aircraft.start_of_roll_directivity(engine=)` | another case (`"JET"` for `"jet"`); spaces around it (`" jet "` for `"jet"`); aliases of its own (`"prop"`, `"propeller"`, `"turbofan"`) | `ValueError` |
| `aircraft.terrain_screening_adjustment(flow_resistivity=)` | another case (`"d"` for `"D"`); spaces around it (`" D "` for `"D"`) | `ValueError` |
| `building.d2m_nt_a(spectrum=)` | another case (`"RAILWAY"` for `"railway"`); spaces around it (`" railway "` for `"railway"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.d2m_nt_atr(spectrum=)` | another case (`"TRAFFIC"` for `"traffic"`); spaces around it (`" traffic "` for `"traffic"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_airborne_requirement(receiving_room=)` | another case (`"PROTECTED"` for `"protected"`); spaces around it (`" protected "` for `"protected"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_airborne_requirement(source_room=)` | another case (`"SAME_UNIT"` for `"same_unit"`); spaces around it (`" same_unit "` for `"same_unit"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_facade_requirement(building_use=)` | another case (`"RESIDENTIAL"` for `"residential"`); spaces around it (`" residential "` for `"residential"`) | `ValueError` |
| `building.db_hr_facade_requirement(dominant_noise=)` | another case (`"ROAD"` for `"road"`); spaces around it (`" road "` for `"road"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_facade_requirement(room_type=)` | another case (`"BEDROOMS"` for `"bedrooms"`); spaces around it (`" bedrooms "` for `"bedrooms"`) | `ValueError` |
| `building.db_hr_global_index(spectrum=)` | another case (`"PINK"` for `"pink"`); spaces around it (`" pink "` for `"pink"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_impact_requirement(receiving_room=)` | another case (`"PROTECTED"` for `"protected"`); spaces around it (`" protected "` for `"protected"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_impact_requirement(source_room=)` | another case (`"OTHER_UNIT"` for `"other_unit"`); spaces around it (`" other_unit "` for `"other_unit"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.db_hr_reverberation_requirement(room_use=)` | another case (`"CLASSROOM"` for `"classroom"`); spaces around it (`" classroom "` for `"classroom"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `building.estimate_reverberation_index(room=)` | another case (`"G"` for `"g"`); spaces around it (`" g "` for `"g"`); aliases of its own (`"other"`, `"others"`) | `ValueError` |
| `building.single_number_uncertainty(quantity=)` | another case (`"R_W"` for `"r_w"`); spaces around it (`" r_w "` for `"r_w"`) | `ValueError` |
| `building.uncertain_value(quantity=)` | another case (`"R_W"` for `"r_w"`); spaces around it (`" r_w "` for `"r_w"`) | `ValueError` |
| `environment.activity_limits(area_type=)` | another case (`"A"` for `"a"`); spaces around it (`" a "` for `"a"`) | `ValueError` |
| `environment.adjacent_premises_limits(building_use=)` | another case (`"RESIDENTIAL"` for `"residential"`); spaces around it (`" residential "` for `"residential"`) | `ValueError` |
| `environment.adjacent_premises_limits(room_type=)` | another case (`"BEDROOMS"` for `"bedrooms"`); spaces around it (`" bedrooms "` for `"bedrooms"`) | `ValueError` |
| `environment.assess_activity(period_hours=)` | another case (keys: `{"Day": 12.0}`); spaces around it (keys: `{" day ": 12.0}`); keys that are not text but print as options | `ValueError`, and `TypeError` for a value that is not text |
| `environment.bridge_transfer(bridge=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.detect_onsets(onset_rate_method=)` | any value: everything but `"upper_half"` exactly was fitted as `"least_squares"` (`"UPPER_HALF"`, `" upper_half "`, `"banana"`, `5`) | `ValueError`, and `TypeError` for a value that is not text |
| `environment.impulsive_sound_adjustment(onset_rate_method=)` | any value: everything but `"upper_half"` exactly was fitted as `"least_squares"` (`"UPPER_HALF"`, `" upper_half "`, `"banana"`, `5`) | `ValueError`, and `TypeError` for a value that is not text |
| `environment.indoor_quality_objectives(building_use=)` | another case (`"RESIDENTIAL"` for `"residential"`); spaces around it (`" residential "` for `"residential"`) | `ValueError` |
| `environment.indoor_quality_objectives(room_type=)` | another case (`"LIVING"` for `"living"`); spaces around it (`" living "` for `"living"`) | `ValueError` |
| `environment.infrastructure_limits(area_type=)` | another case (`"E"` for `"e"`); spaces around it (`" e "` for `"e"`) | `ValueError` |
| `environment.max_infrastructure_limit(area_type=)` | another case (`"E"` for `"e"`); spaces around it (`" e "` for `"e"`) | `ValueError` |
| `environment.measured_insertion_loss_indirect(receiver_type_after=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.measured_insertion_loss_indirect(receiver_type_before=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.outdoor_quality_objectives(area_type=)` | another case (`"E"` for `"e"`); spaces around it (`" e "` for `"e"`) | `ValueError` |
| `environment.outdoor_quality_objectives(urbanization=)` | another case (`"EXISTING"` for `"existing"`); spaces around it (`" existing "` for `"existing"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `environment.pass_by_regression(vehicle_category=)` | spaces around it (`" 1 "` for `"1"`); a number (`1` for `"1"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `environment.rail_roughness(roughness=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_propulsion_noise(category=)` | a number (`1` for `"1"`); a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_propulsion_noise(surface=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_rolling_noise(category=)` | a number (`1` for `"1"`); a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_rolling_noise(surface=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_source_power(surface=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_surface_coefficients(surface=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_vehicle_sound_power(category=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.road_vehicle_sound_power(surface=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.statistical_pass_by(corrected_vehicle_sound_levels=)` | another case (keys: `{"1": 78.8, "2A": 81.1, "2B": 83.8}`); spaces around it (keys: `{" 1 ": 78.8, " 2a ": 81.1, " 2b ": 83.8}`); keys that are not text but print as options | `ValueError`, and `TypeError` for a value that is not text |
| `environment.statistical_pass_by(reference_levels=)` | another case (keys: `{"1": 80.0, "2A": 85.0, "2B": 89.0}`); spaces around it (keys: `{" 1 ": 80.0, " 2a ": 85.0, " 2b ": 89.0}`); keys that are not text but print as options | `ValueError`, and `TypeError` for a value that is not text |
| `environment.statistical_pass_by(weighting_factors=)` | another case (keys: `{"1": 0.9, "2A": 0.075, "2B": 0.025}`); spaces around it (keys: `{" 1 ": 0.9, " 2a ": 0.075, " 2b ": 0.025}`); keys that are not text but print as options | `ValueError`, and `TypeError` for a value that is not text |
| `environment.statistical_pass_by_index(vehicle_sound_levels=)` | another case (keys: `{"1": 78.5, "2A": 81.1, "2B": 83.8}`); spaces around it (keys: `{" 1 ": 78.5, " 2a ": 81.1, " 2b ": 83.8}`); keys that are not text but print as options | `ValueError`, and `TypeError` for a value that is not text |
| `environment.statistical_pass_by_index(weighting_factors=)` | another case (keys: `{"1": 0.8, "2A": 0.1, "2B": 0.1}`); spaces around it (keys: `{" 1 ": 0.8, " 2a ": 0.1, " 2b ": 0.1}`); keys that are not text but print as options | `ValueError`, and `TypeError` for a value that is not text |
| `environment.track_transfer(track=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.traction_sound_power(vehicle=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `environment.vibration_quality_objective(building_use=)` | another case (`"RESIDENTIAL"` for `"residential"`); spaces around it (`" residential "` for `"residential"`) | `ValueError` |
| `environment.wheel_roughness(brake=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `filters.OctaveFilterBank.filter(mode=)` | another case (`"RMS"` for `"rms"`) | `ValueError` |
| `filters.OctaveFilterBank.spectrogram(mode=)` | another case (`"RMS"` for `"rms"`) | `ValueError` |
| `filters.TimeWeighting(mode=)` | another case (`"FAST"` for `"fast"`) | `ValueError` |
| `filters.WeightingFilter(weighting=)` | another case (`"a"` for `"A"`) | `ValueError` |
| `filters.time_weighting(initial_state=)` | another case (`"ZERO"` for `"zero"`) | `ValueError` |
| `filters.time_weighting(mode=)` | another case (`"FAST"` for `"fast"`) | `ValueError` |
| `fluids.sea_water(sound_speed_model=)` | another case (`"UNESCO"` for `"unesco"`); spaces around it (`" unesco "` for `"unesco"`) | `ValueError` |
| `fluids.sea_water_sound_speed(model=)` | another case (`"MACKENZIE"` for `"mackenzie"`); spaces around it (`" mackenzie "` for `"mackenzie"`) | `ValueError` |
| `materials.check_ceiling_specimen(mounting=)` | another case (`"e"` for `"E"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `materials.mounting_type(letter=)` | another case (`"e"` for `"E"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `metrology.CalibratorTableRow.for_class(calibrator_class=)` | another case (`"1/m"` for `"1/M"`); spaces around it (`" 1 "` for `"1"`); a number (`1` for `"1"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `metrology.sensitivity(calibrator_class=)` | spaces around it (`" 1 "` for `"1"`); a number (`1` for `"1"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `metrology.verify_sound_calibrator(calibrator_class=)` | spaces around it (`" 1 "` for `"1"`); a number (`1` for `"1"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `metrology.verify_sound_calibrator(environmental_test=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.applicable_methods(condition=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.applicable_methods(source_kind=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.cabin_insulation(method=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.check_enclosure_test_environment(base_standard=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.enclosure_artificial_source_insulation(condition=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.enclosure_artificial_source_insulation(quantity=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.enclosure_sound_power_insulation(condition=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.enclosure_sound_power_insulation(source_kind=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.enclosure_sound_pressure_insulation(condition=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.enclosure_sound_pressure_insulation(source_kind=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.screen_attenuation(source_kind=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.uncertainty_conditions(method=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.weighted_cabin_insulation(method=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `noise_control.weighted_enclosure_insulation(quantity=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `signals.ln_levels(mode=)` | another case (`"FAST"` for `"fast"`) | `ValueError` |
| `signals.ln_levels(weighting=)` | another case (`"a"` for `"A"`) | `ValueError` |
| `signals.sel(weighting=)` | another case (`"a"` for `"A"`) | `ValueError` |
| `underwater.VolumeAbsorption(model=)` | another case (`"THORP"` for `"thorp"`); spaces around it (`" thorp "` for `"thorp"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.WeightedExposureResult(group=)` | another case (`"vhf"` for `"VHF"`); spaces around it (`" VHF "` for `"VHF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.WeightedExposureResult(guidance=)` | another case (`"NMFS-2024"` for `"nmfs-2024"`); spaces around it (`" nmfs-2024 "` for `"nmfs-2024"`); another separator (`"nmfs_2024"` for `"nmfs-2024"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.audiogram_parameters(group=)` | another case (`"hf"` for `"HF"`); spaces around it (`" HF "` for `"HF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.auditory_weighting(group=)` | another case (`"hf"` for `"HF"`); spaces around it (`" HF "` for `"HF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.auditory_weighting(guidance=)` | another case (`"NMFS-2018"` for `"nmfs-2018"`); spaces around it (`" nmfs-2018 "` for `"nmfs-2018"`); another separator (`"nmfs_2018"` for `"nmfs-2018"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.detection_range(law=)` | another case (`"SPHERICAL"` for `"spherical"`); spaces around it (`" spherical "` for `"spherical"`) | `ValueError` |
| `underwater.detection_range(model=)` | another case (`"FRANCOIS-GARRISON"` for `"francois-garrison"`); spaces around it (`" francois-garrison "` for `"francois-garrison"`) | `ValueError` |
| `underwater.detection_range_from_curve(crossing=)` | another case (`"FIRST"` for `"first"`); spaces around it (`" first "` for `"first"`) | `ValueError` |
| `underwater.effective_depth(seabed=)` | another case (`"SAND"` for `"sand"`); spaces around it (`" sand "` for `"sand"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.eigenrays(bottom=)` | another case (`"PRESSURE-RELEASE"` for `"pressure-release"`); spaces around it (`" pressure-release "` for `"pressure-release"`) | `ValueError` |
| `underwater.exposure_criteria(group=)` | another case (`"lf"` for `"LF"`); spaces around it (`" LF "` for `"LF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.exposure_criteria(guidance=)` | another case (`"SOUTHALL-2019"` for `"southall-2019"`); spaces around it (`" southall-2019 "` for `"southall-2019"`); another separator (`"southall_2019"` for `"southall-2019"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.gaussian_beams(bottom=)` | another case (`"RIGID"` for `"rigid"`); spaces around it (`" rigid "` for `"rigid"`) | `ValueError` |
| `underwater.group_audiogram(group=)` | another case (`"hf"` for `"HF"`); spaces around it (`" HF "` for `"HF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.hearing_groups(guidance=)` | another case (`"SOUTHALL-2019"` for `"southall-2019"`); spaces around it (`" southall-2019 "` for `"southall-2019"`); another separator (`"southall_2019"` for `"southall-2019"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.normal_modes(bottom=)` | another case (`"PRESSURE-RELEASE"` for `"pressure-release"`); spaces around it (`" pressure-release "` for `"pressure-release"`) | `ValueError` |
| `underwater.propagation_loss(law=)` | another case (`"SPHERICAL"` for `"spherical"`); spaces around it (`" spherical "` for `"spherical"`) | `ValueError` |
| `underwater.propagation_loss(model=)` | another case (`"FRANCOIS-GARRISON"` for `"francois-garrison"`); spaces around it (`" francois-garrison "` for `"francois-garrison"`) | `ValueError` |
| `underwater.reflection_loss_gradient(seabed=)` | another case (`"SAND"` for `"sand"`); spaces around it (`" sand "` for `"sand"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.seawater_absorption(model=)` | another case (`"THORP"` for `"thorp"`); spaces around it (`" thorp "` for `"thorp"`) | `ValueError` |
| `underwater.ship_source_spectrum(model=)` | another case (`"JOMOPANS-ECHO"` for `"jomopans-echo"`); spaces around it (`" jomopans-echo "` for `"jomopans-echo"`) | `ValueError` |
| `underwater.ship_source_spectrum(vessel_class=)` | another case (`"BULKER"` for `"bulker"`); spaces around it (`" bulker "` for `"bulker"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.sound_speed_profile(model=)` | another case (`"MEDWIN"` for `"medwin"`); spaces around it (`" medwin "` for `"medwin"`) | `ValueError` |
| `underwater.spreading_loss(law=)` | another case (`"SPHERICAL"` for `"spherical"`); spaces around it (`" spherical "` for `"spherical"`) | `ValueError` |
| `underwater.waveguide_cutoff_frequency(seabed=)` | another case (`"SAND"` for `"sand"`); spaces around it (`" sand "` for `"sand"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.weighted_exposure(group=)` | another case (`"vhf"` for `"VHF"`); spaces around it (`" VHF "` for `"VHF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.weighted_exposure(guidance=)` | another case (`"NMFS-2024"` for `"nmfs-2024"`); spaces around it (`" nmfs-2024 "` for `"nmfs-2024"`); another separator (`"nmfs_2024"` for `"nmfs-2024"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.weighting_parameters(group=)` | another case (`"hf"` for `"HF"`); spaces around it (`" HF "` for `"HF"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.weighting_parameters(guidance=)` | another case (`"NMFS-2018"` for `"nmfs-2018"`); spaces around it (`" nmfs-2018 "` for `"nmfs-2018"`); another separator (`"nmfs_2018"` for `"nmfs-2018"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.weston_propagation_loss(seabed=)` | another case (`"SAND"` for `"sand"`); spaces around it (`" sand "` for `"sand"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `underwater.weston_regime_boundaries(seabed=)` | another case (`"SAND"` for `"sand"`); spaces around it (`" sand "` for `"sand"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `vibration.PhaseVerification(weighting=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.RunningRMSDecayVerification(method=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.WeightingVerification(weighting=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.admissible_exposure_s(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.angular_average_transmission_coefficient(junction=)` | another case (`"x"` for `"X"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `vibration.angular_average_transmission_coefficient(section=)` | another case (`"CORNER"` for `"corner"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `vibration.assess_people_in_buildings(source=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.assess_railway_change(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.assessment_vibration_severity(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.band_limited_weighting_factor(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.check_loose_mounting(direction=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.check_loose_mounting(surface=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.construction_guide_values(area=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.construction_guide_values(stage=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.corner_transmission_coefficient(junction=)` | another case (`"x"` for `"X"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `vibration.foundation_to_floor_level_difference(floor=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.foundation_to_floor_level_difference(statistic=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.geometric_exponent(character=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.geometric_exponent(geometry=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.geometric_exponent(wave=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.ground_to_floor_level_difference(floor=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.ground_to_foundation_level_difference(level=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.ground_to_foundation_level_difference(statistic=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.guide_values(area=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.guide_values(edition=)` | a number (`1999` for `"1999"`); a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.guide_values(source=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.guide_values(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.indication_tolerance_percent(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.instrument_confidence_limit_percent(quantity=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.junction_transmission(junction=)` | another case (`"l"` for `"L"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `vibration.kb_fmax_from_peak_velocity(kind=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.phase_tolerance_deg(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.railway_assessment_severity(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.railway_guide_values(alignment=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.railway_guide_values(area=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.railway_guide_values(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.reference_indication(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.running_rms_decay_time(method=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.sawtooth_burst(application=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.signal_burst_indications(application=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.signal_burst_indications(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.straight_transmission_coefficient(junction=)` | another case (`"t1"` for `"T1"`); a value that is not text but prints as an option | `ValueError`, and `TypeError` for a value that is not text |
| `vibration.train_assessment_severity(time_of_day=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.train_decay_exponent(fitted_with=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.train_weighting_factor(alignment=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.train_weighting_factor(kind=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.verify_phase_response(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.verify_running_rms_decay(method=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.verify_signal_burst_response(application=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.verify_signal_burst_response(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.verify_weighting(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |
| `vibration.weighting_tolerance_percent(name=)` | a value that is not text but prints as an option | `TypeError` for a value that is not text |

## A record refuses a choice when it is built

A record a caller builds checks each field typed with a `Literal` in its
`__post_init__`, as written: a text it does not offer raises `ValueError` and
a value that is not a text raises `TypeError`, when the record is built.
Before 4.0 most of them stored any value and left it to whatever read it,
so a misspelling failed later, in another call, or not at all; the four
that did check refused a value that is not text with `ValueError`. The fix is to
write the option as its `Literal` lists it where the record is built.

| Record | Before 4.0 | 4.0 |
| --- | --- | --- |
| `aircraft.ANPNPDCurves(metric=, operation=)` | stored any value, refused later or not at all | refused when built |
| `aircraft.SpectralClass(operation=)` | stored any value, refused later or not at all | refused when built |
| `aircraft.RotorcraftAtmosphere(atmospheric_method=)` | stored any value, refused later or not at all | refused when built |
| `aircraft.RotorcraftGround(flow_resistivity=)` | stored any value, refused later or not at all | `ValueError` for a letter it does not offer and for one number that is not positive and finite, `TypeError` for a value that is neither a letter nor numbers (a `bytes`, `None`, a complex value, a text among numbers), when built |
| `building.BandPath(kind=)` | stored any value, refused later or not at all | refused when built |
| `building.FlankingPath(kind=)` | stored any value, refused later or not at all | refused when built |
| `electroacoustics.MicrophoneNoise(weighting=)` | stored any value, refused later or not at all | refused when built |
| `emission.MicrophoneTraverse(targets=)` | `ValueError` for any target it did not know, text or not | `ValueError` for a text it does not offer, `TypeError` for a target that is not text |
| `environment.BinnedSoundLevels(averaging=)` | stored any value, refused later or not at all | refused when built |
| `environment.RoadEmissionCoefficients` (the category keys of its per-category tables) | stored any key, refused later or not at all | `ValueError` for a text that is not a code of Table [2.2.a], `TypeError` for a key that is not text, each key when built |
| `environment.RoadSurfaceCoefficients(alpha=, beta=)` (their category keys) | stored any key, refused later or not at all | `ValueError` for a text that is not a code of Table [2.2.a], `TypeError` for a key that is not text, each key when built |
| `filters.FilterDesign(filter_type=)` | stored any value, refused later or not at all | refused when built |
| `filters.EQSection(filter_type=)` | `ValueError` for any value it did not know, text or not | `ValueError` for a text it does not offer, `TypeError` for a value that is not text |
| `hearing.Task(instrument=)` | stored any value, refused later or not at all | refused when built |
| `materials.FiberResistivityFit(direction=)` | stored any value, refused later or not at all | refused when built |
| `metrology.SoundLevelMeterPeriodicMeasurements` (the keys of its per-weighting, per-range and per-response mappings) | `ValueError` for any key it did not know | `ValueError` for a text it does not know, `TypeError` for a key that is not a text, each key when built |
| `noise_control.DesignCriterion(family=)` | stored any value, refused later or not at all | refused when built |
| `noise_control.SourceRoom(model=)` | stored any value, refused later or not at all | refused when built |
| `noise_control.LiquidTrim(coefficient=)` | stored any value, refused later or not at all | refused when built |
| `noise_control.ValveTrim(coefficient=)` | stored any value, refused later or not at all | refused when built |
| `phonometry.ReportMetadata(tube_shape=)` | `ValueError` for any value it did not know, text or not | `ValueError` for a text it does not offer, `TypeError` for a value that is not text |
| `simulation.ElasticBoundaries(sides=)` | stored any value; the run that held the record refused an unknown side or name with `ValueError`, text or not | `ValueError` for a side or a name it does not offer, `TypeError` for one that is not text, when built |
| `simulation.FDTDBoundaries(sides=)` | stored any value; the run that held the record refused an unknown side or name with `ValueError`, text or not, ran a flag as an impedance of 1 Pa s/m and refused `None` as an impedance that is not finite | `ValueError` for a side or a name it does not offer, `TypeError` for a side that is not text and for a termination that is neither a name nor a real number or an array of them (a flag, `None`, a flag among the numbers of a profile), when built; an impedance is held as a float, a profile as a read-only float64 array |
| `simulation.ElasticRecording(probe_fields=, snapshot_field=)` | `ValueError` for any field it did not know, text or not; `probe_fields="vy"` was read a letter at a time and refused `"v"` | `ValueError` for a text it does not offer, `TypeError` for a field that is not text; a single name records that one field |
| `simulation.ForceSource(direction=)` | `ValueError` for any direction it did not know, text or not | `ValueError` for a text other than `"x"` and `"y"`, `TypeError` for a value that is not text |
| `simulation.PlaneWaveSource(direction=)` | stored any value; `FDTD2D.add_source` and the run that held it refused one it did not know | refused when built |
| `vibration.GuideValues(time_of_day=, edition=)` | stored any value, refused later or not at all | refused when built |
| `vibration.FaultLine(family=)` | stored any value, refused later or not at all | refused when built |

A choice is checked on every path of the functions too. One read on some
paths only took any value on the others, and one checked with a comparison
refused a value that is not text with `ValueError`, or with an unrelated
error:

| Call | Before 4.0 | 4.0 |
| --- | --- | --- |
| `environment.ground_effect(model=)` | took any value without `flow_resistivity_pa_s_m2` | `ValueError` for a text it does not offer, `TypeError` for a value that is not text, whatever else is given |
| `environment.barrier_insertion_loss(ground_model=)` | took any value without `ground_flow_resistivity_pa_s_m2` | the same |
| `environment.atmospheric_parabolic_equation(model=)` | took any value without `flow_resistivity_pa_s_m2` | the same |
| `metrology.coupler_transfer_impedance(heat_conduction_method=)` | took any value with a `PlaneWaveCoupler` | the same |
| `noise_control.elbow_insertion_loss(lined_side=)` | took any value with `model="ashrae"` | the same |
| `noise_control.fan_sound_power(assembly=)` | took any value with `model="ashrae"` | the same |
| `noise_control.fan_sound_power(fan_type=)` | took any value with `model="vdi2081"` | the same |
| `signals.time_delay(weighting=)` | took any value unless `method="gcc"` | the same |
| `underwater.ship_source_spectrum(vessel_class=)` | took any value unless `model="jomopans-echo"` | the same |
| `emission.reference_source_calibration(arrangement=)`, `emission.reference_source_reproducibility(arrangement=)` | took any value in a reverberation room | the same; `None` is still taken there |
| `building.single_number_uncertainty(situation=)` with `upper_limit=True` | `ValueError` for anything but `"A"`, text or not | `ValueError` for a text other than `"A"`, `TypeError` for a value that is not text |
| `io.write(subtype=)` with integer samples | `ValueError` for anything but the samples' own subtype, text or not | `TypeError` for a value that is not text |
| `io.write_catalogue(delimiter=, decimal=)` beside a JSON document | `ValueError` for anything but the default dialect, text or not | `TypeError` for a value that is not text |
| `underwater.gaussian_beams(absorption=)` | `AttributeError` for a value that is neither text nor a `VolumeAbsorption` | `TypeError` |
| `filters.FilterPeriodicVerification.clause()` | `KeyError` for any name it had not measured | `ValueError` for a text that names none of the five clauses, `TypeError` for a value that is not text; `KeyError` for a clause that was not measured |
| `simulation.FDTD2D(absorbing_sides=, edge_impedance=)`, `simulation.ElasticFDTD2D(absorbing_sides=, free_sides=)` | `ValueError` for any side it did not know, text or not, its message listing the unknown sides | `ValueError` for a text that is not a side, `TypeError` for a side that is not text, its message the one every choice raises (`'free_sides' must be one of ('left', 'right', 'top', 'bottom'); got 'north'.`) |
| `simulation.FDTD2D.add_plane_wave(direction=)`, `simulation.ElasticFDTD2D.collocated(field)`, `simulation.FDTDResult.plot(kind=)`, `simulation.ElasticFDTDResult.plot(kind=)` | `ValueError` for any value it did not know, text or not | `ValueError` for a text it does not offer, `TypeError` for a value that is not text |
| `simulation.FDTD2D(edge_impedance=)` with an impedance that is no real number | a flag, alone or among the numbers of a profile, ran as an impedance of 1 Pa s/m, `None` raised `ValueError` as an impedance that is not finite, a text `ValueError` from the float conversion | `TypeError` |

A key of a mapping and an item of a sequence is checked one by one:
`environment.assess_activity` ignored a period key it did not know beside one
it knew and now raises `ValueError` for it; a key of
`environment.pleasantness_eventfulness` that is not text raised `ValueError`
and now raises `TypeError`; the sound field checks of ISO 8253-2, ISO 4869-1
and ISO 4869-3 met such a key with an unrelated `TypeError` from sorting and
now name the parameter; the keys of the reference track decay limits and of
a silencer drawing's `geometry` raise `TypeError` when they are not text; a
key of a duct `section` that
`noise_control.duct_path` does not take raised the `TypeError` of an unknown
keyword and now raises `ValueError`; and the uncertainty budgets of the comparison, the
reciprocity and the free-field corrections keep their message for an unknown
component and raise `TypeError` for a key that is not text. Twelve `.plot()`
of the hearing protector, active noise reduction, real-ear attenuation and
ISO 15186-3 low-frequency results, and `building.SoundReductionResult.report`,
took any `language` and now refuse one they do not offer, as every other plot
does. A typed caller that indexes a published table with a free `str` (a
`str` variable into `room.TABLE_A1` or `hearing.EARPHONES`) needs the
`Literal` the table is keyed by now; the values did not move.

The sponge thickness of `simulation.FDTDBoundaries` and
`simulation.ElasticBoundaries` is held as the whole number of cells it names
and checked when the record is built: a value that is not a number raises
`TypeError` and a fraction `ValueError`, where it was stored as given and read
only by a run with an absorbing side (`FDTDBoundaries(sides="rigid",
absorbing_layer_cells=2.5)` was built and run). A `shape` given to
`simulation.FDTD2D`, `simulation.ElasticFDTD2D`, `simulation.FDTDRun` or
`simulation.ElasticRun` is read whenever it is given: a run holds it as a pair
of ints, from any sequence of the two counts (a list or a `range` too) or a
one-dimensional integer array, where only a tuple or a list was taken, a
malformed one is refused beside a map too, and one
that names a grid other than the map's raises `ValueError` (`shape (4, 8) does
not match the c map, whose shape is (8, 8)`), where an engine ignored a shape
beside a map and a run held it as given.
`simulation.ElasticFDTD2D.from_regions` reads its `shape` the same way: a
third count raises `ValueError` and a text `TypeError`, where the third count
was dropped. A `numpy` integer is taken wherever these records and the engines
take a count, and nested lists wherever they take a map. A
`simulation.ContourProbe` built by hand, `ContourProbe(engine, ix0, ix1, iy0,
iy1, frequencies)`, joins its engine and samples from the next step, as the one
`FDTD2D.add_contour_probe` returns does; it never sampled, and its `phasors`
refused for want of samples. Anything but an `FDTD2D` as its `engine` raises
`TypeError` naming `engine`, where an `ElasticFDTD2D`, `None` or any other
object failed with an `AttributeError` that named a private attribute or the
pressure field.

## A record a caller builds holds what its fields say

Before 4.0 a record kept a list, a tuple or an array of the wrong kind exactly
as it was handed, though its field said it held an array or a tuple:
`environment.WavelengthSpectrum(levels=[...])` held the list, so
`spectrum.levels * 2` repeated the list instead of doubling the levels, and
the frozen record held a list anyone could still append to. In 4.0 a record a
caller builds converts what it is given and holds what its field says: an
array field holds a read-only array of its dtype, a tuple field a tuple and a
pair a pair of numbers, and a single number where a per-band value may be one
stays the number it was. Code that appended to a list it had handed a record,
or read a field back expecting the list it gave, reads the array now:
`record.levels.tolist()` gives the list. A type checker reads the constructor
each of these records declares for it, so a list type-checks where the
record converts one.

| Record | Before 4.0 | 4.0 |
| --- | --- | --- |
| `aircraft.ANPNPDCurves(powers=, distances_m=, levels=)` | kept a list as given | read-only `float64` arrays |
| `aircraft.FlightSegmentState(ground_roll=, landing_roll=, bank=)` | kept a list as given | read-only arrays, the masks `bool` and the bank `float64` |
| `aircraft.FlightConditionInterpolation(triangles=)` | kept a list of rows as given | a read-only integer array |
| `aircraft.PerformanceAircraft(jet_coefficients=, propeller_coefficients=, aerodynamic_coefficients=)` | kept the dictionaries as given, the database's own included, so a table could be edited after the aeroplane was checked | read-only copies (`dict(aircraft.jet_coefficients)` gives one to edit) |
| `aircraft.RotorcraftGround(ground_elevation=, flow_resistivity=, terrain=)` | kept a list as given; an elevation model of other than three axes was refused when an event read it | a value per receiver as a read-only `float64` array and the elevation model as its three axes, each a read-only `float64` array; an elevation model of other than three axes refused with `ValueError` when built; one number or a class letter as given; a text among the numbers of any of them refused with `TypeError`, and one ground elevation that is not finite with `ValueError`, when built |
| `aircraft.RotorcraftHemisphere(frequencies=, azimuth_deg=, polar_deg=, levels=)` | kept a list as given | read-only `float64` arrays |
| `aircraft.RotorcraftTrackState(airspeed=, path_angle_deg=, heading=, bank_angle_deg=)` | kept a list as given | a sequence as a read-only `float64` array; one number as given |
| `building.BandPath(values=)` | kept a list as given | a read-only `float64` array |
| `building.FacadeElement(r=, dn_e=, insertion_loss=)` | kept a list as given | a value per band as a read-only `float64` array; one number as given |
| `building.LowFrequencyProcedure(corner_levels=)` | kept the list as given | a read-only `float64` array |
| `electroacoustics.LoudspeakerDirectivity(polar=)`, `electroacoustics.MicrophoneDirectivity(polar=)`, `electroacoustics.MicrophoneNoise(spectrum=)`, `electroacoustics.MicrophoneOverload(distortion=)` | kept the pair as given, a list included; anything but a pair failed when it was read | a tuple of two read-only `float64` arrays; `TypeError` for a number or a text, or for a text or a complex value among the numbers of a member, and `ValueError` for other than two members, when built |
| `electroacoustics.LoudspeakerRatings(frequency_range=)` | kept the pair as given, checked when it was read | a `(low, high)` pair of floats, checked when built as the other frequency pairs are (`TypeError`, `ValueError`) |
| `emission.RoomEnvironment(absorption_area=, reverberation_time=, mean_absorption_coefficient=)` | kept a list as given | a value per band as a read-only `float64` array; one number as given |
| `environment.AtmosphericAttenuation(frequencies, attenuation_db_per_m, ...)` | kept a list as given | read-only `float64` arrays |
| `environment.WavelengthSpectrum(wavelengths_mm=, levels=)`, `environment.RailSourceSpectra(source_a=, source_b=)` | kept a list as given | read-only `float64` arrays |
| `environment.RollingStock(wheel_transfer=, superstructure_transfer=)`, `environment.RailwayTrack(track_transfer=, bridge_transfer=)` | kept a list or a tuple as given | read-only `float64` arrays |
| `environment.RoadEmissionCoefficients(studded_a=, studded_b=)` | kept a list or an array as given | a tuple of floats; `TypeError` for a number, a text or a member that is not one number |
| `environment.RoadSurfaceCoefficients(speed_range_kmh=, alpha=, beta=)` | kept the pair and the two dictionaries as given, so the tables could be edited after the row was built | a pair of floats (`TypeError` for a number, a text or a member that is not one number, `ValueError` for other than two) and two read-only mappings |
| `hearing.Task(samples=, duration_observations_hours=, duration_range_hours=)` | kept a list or an array as given | tuples of floats, the range a pair; `TypeError` for a number or a text given as the observations or the range, `ValueError` for a range of other than two values |
| `io.Signal(channel_labels=)` | kept a list as given; one text of as many letters as channels named a channel per letter | a tuple; `TypeError` for one text |
| `materials.FiberResistivityFit(bulk_density_range_kg_m3=)` | kept a list as given | a pair of floats; `TypeError` for a number or a text, `ValueError` for other than two values |
| `materials.MetadiffuserWell(resonators=)` | kept a list as given | a tuple |
| `materials.TransferMatrix(t11, t12, t21, t22, frequencies=)` | kept each entry as given: a `complex`, a list or a real array | read-only `complex128` arrays: a scalar entry is a 0-d array, no longer a `complex` and no longer hashable (`complex(m.t11)` or `m.t11.item()` gives the number), and a real entry has a zero imaginary part; `frequencies` a read-only `float64` array |
| `room.ImpulseResponseResult(ir=)` | kept a list as given | a read-only `float64` array |
| `vibration.MultipleShockResult(peaks=, risk_thresholds=)` | kept a list as given | the peaks a read-only `float64` array and the thresholds a tuple of three floats; `TypeError` for a number or a text and `ValueError` for other than three thresholds |
| `vibration.TransferStiffnessResult(frequencies=, transfer_stiffness=, transmissibility=)` | kept a list as given | read-only arrays, the frequencies `float64`, the stiffness and the transmissibility `complex128` (a real value with a zero imaginary part) |

Four results that held a `dict` a caller could edit hold a read-only mapping
instead, as the published tables do, and an assignment into one raises
`TypeError`: `building.FacadePredictionResult.element_r`,
`environment.RailwayEmissionResult.components`,
`noise_control.ReactiveSilencerResult.geometry` and
`psychoacoustics.MooreGlasbergTimeVaryingLoudness.percentiles`. Code that
edited one copies it first, with `dict(result.element_r)`. The band centres
and the band waveforms of the `filters.OctaveFilterResult` that
`filters.octave_filter` and `OctaveFilterBank.filter` return are tuples where
they were lists, the lists a caller could still append to:
`result.frequencies.index(1000.0)` and indexing read as before, and
`list(result.frequencies)` gives a list to edit. A range or a set of numbers
given as a text (`"12"`) is refused with a `TypeError` that names the field,
whatever the text reads as. A record that comes back from `pickle` or
`copy.deepcopy` holds its arrays read-only, as it held them when it left,
where they came back writeable: `np.array(record.levels)` gives a copy to
write into.

```python
from phonometry import environment, materials

spectrum = environment.WavelengthSpectrum(wavelengths_mm=[2000.0, 1600.0], levels=[5.0, 4.0])
matrix = materials.TransferMatrix(1.0, 0.0, 0.0, 1.0)
print(type(spectrum.levels).__name__, spectrum.levels.flags.writeable, spectrum.levels.tolist())
print(matrix.t11.shape, matrix.t11.dtype, complex(matrix.t11))
# ndarray False [5.0, 4.0]
# () complex128 (1+0j)
```

## A reader refuses a name that holds no regular file

A name handed to a reader can hold something other than a file. A named pipe
no one writes to kept `io.read` waiting at its first open for a writer that
never came, and the tables of an ANP export the same way; a link to
`/dev/zero` kept a read going, and a directory raised whatever its first open
raised. In 4.0 each reader looks at the name before it opens it and raises a
`ValueError` that names the file and what it holds. A call that caught
`OSError` for a directory catches `ValueError` now; a name with nothing at it
still raises `FileNotFoundError`, and a link to a regular file is still read.

| Passed | 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| a named pipe to `io.read`, `io.info`, `io.read_blocks` or as the source of `io.convert` | the call waited at the open for a writer | `ValueError`: `"<path>: is a named pipe (FIFO), and audio is read only from a regular file"` |
| a directory to the same four | `IsADirectoryError` (`PermissionError` on Windows) | `ValueError`, `"... is a directory, ..."` |
| a device to the same four (`/dev/zero`, or a link to it) | `ValueError`: not a recognised audio file | `ValueError`, `"... is a character device, ..."` |
| a directory to `aircraft.load_anp_database` holding a pipe, a device or a directory under the name of one of its tables | the call waited, read without end, or raised `IsADirectoryError` | `ValueError`, `"ANP table <path>: is ..., and an ANP table is read only from a regular file"`; a file whose name no table keyword matches is no longer opened at all |
| an ANP table of more than 32 MiB | read whole | `ValueError`, before a byte of it is read |
| an ANP cell of `nan`, `inf`, `-Infinity` or `1e999`, a heading such as `L_infft`, or a cell that holds no number | a non-finite cell was taken as it was and came out of every event level as NaN; a cell with no number raised Python's own `ValueError`, which named neither the table nor the line | `ValueError` naming the table, the line and the column |
| an ANP table that is not UTF-8 | `UnicodeDecodeError`, naming no file | `ValueError` naming the table and the byte |
| an ANP count (a stage length, a point or step number, a number of engines) of `1.5`, or a number of engines left blank | taken as `1`, and the blank number of engines as `0`; a stage length of the weights or the departure steps, so written or `nan`, raised the `ValueError` of a `stage_length` argument, which named no table | `ValueError` naming the table, the line and the column |

```python
import tempfile
from pathlib import Path

from phonometry import io

with tempfile.TemporaryDirectory() as folder:
    try:
        io.read(Path(folder))
    except ValueError as refusal:
        print(str(refusal).split(": ", 1)[1])
# is a directory, and audio is read only from a regular file
```

## A path of another library reaches the file it names

`io.write`, `io.read`, `io.info`, `io.read_blocks` and `io.convert` handed a
path to SciPy and python-soundfile as `str(path)`. For a `str` or a
`pathlib.Path` that is the path; for any other `os.PathLike`, an `os.DirEntry`
or a path class of another library, it is the object's repr. In 4.0 each of
them takes the path the object names, the messages print it, and the
annotations say `str | os.PathLike[str]`, as the video writers' did. A `str`
or a `pathlib.Path` behaves as before.

| Passed | 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| an `os.PathLike` that is neither a `str` nor a `pathlib.Path`, to `io.write` (a WAV of 16 or 32 bits, a float WAV, a FLAC, or `bext="loudness"`) | the file went to a name made of the object's repr, `<... object at 0x...>`, in the working directory | the file the object names |
| the same to `io.read`, or as the source of `io.convert`, and a FLAC to `io.info` or `io.read_blocks` | `FileNotFoundError` naming the repr, or python-soundfile's `LibsndfileError` for a FLAC | the file the object names is read |
| the same to `io.info` | `AudioFileInfo.path` held the repr | `AudioFileInfo.path` is the path |

## A writer puts its file at the name only once it is whole

`io.write`, the target of `io.convert`, every `.report()` and the response
plot of a filter bank wrote straight at the name they were given. An error or
an interrupt half way left a file begun there, over the recording or the fiche
of an earlier run, and a fiche too long for its page was built at the name and
removed again, the earlier fiche with it. In 4.0, with nothing at the name or
a regular file, each writes a hidden file beside it and renames it over the
name once it is whole, with the old file's permission bits, and readable by
its owner alone while it is written over a file. The new file is the writer's
own: it takes the writer's owner and group, and keeps neither the access
control lists nor the extended attributes of the old file. Its hidden name is
cut to what the directory takes, so a name as long as the directory allows is
written as any other. A link, a pipe, a device or a directory at the name is
opened there as before, so a recording streamed into a pipe on purpose still
goes into the pipe.

| Passed | 3.3.0 or 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| a write, a conversion, a fiche or a response plot stopped half way by an error or an interrupt | a file begun at the name, in place of what was there | the name as it was, and nothing beside it |
| a fiche too long for its page, at the name of an earlier fiche | `ValueError`, and the earlier fiche removed | `ValueError`, and the earlier fiche kept |
| a name whose file has a hard link elsewhere | the new bytes in the file, so under both names | the new file at the name; the other name keeps the old bytes |
| a writable file in a directory that takes no new file | written in place | the `PermissionError` of the file beside it, the old file kept |

## The lobe patterns of a ducted fan are speeds of rotation, not lines

`vibration.blade_pass_frequencies(..., n_vanes=...)` returned the rotating
interaction patterns of a ducted fan among its lines, as `FaultLine` entries of
family `"blade"` named `lobe n=1 m=2`, with the speed of Eq. (8.17) as the
line's frequency in hertz. Norton puts the noise of those patterns at the
blade-passing harmonic they come from, so a spectrum has no line at those
speeds, and `.plot()` and `combine_fault_lines` marked one anyway. The lobe
count lost its sign too, which is the sense in which the pattern turns.

In 4.0 the function returns a `BladePassResult`, a `FaultFrequencyResult` whose
lines are the shaft and blade tones alone, and holds the patterns apart in
`lobe_patterns`, one `LobePattern` per blade harmonic and signed vane order:
`harmonic`, `vane_order`, `n_lobes` (negative for a pattern turning against the
rotor) and `speed_rpm`, the speed of Eq. (8.17) in r/min, as Norton prints it.
`within` keeps the patterns; `combine_fault_lines` merges the lines only.

| 4.0.0rc1 | 4.0 |
| --- | --- |
| `res["lobe n=N m=M"]`, the unsigned speed in hertz of the pattern of blade harmonic `N` with `M` lobes either way | `abs(next(p for p in res.lobe_patterns if p.harmonic == N and abs(p.n_lobes) == M).speed_rpm) / 60` |
| `res.names` with `lobe n=… m=…` entries | `res.names` with the shaft and blade lines only; the patterns in `res.lobe_patterns` |
| a pattern with $m_\mathrm{L} < 0$ named by $\lvert m_\mathrm{L} \rvert$, its speed positive | `n_lobes` and `speed_rpm` negative, and a pattern of $+m_\mathrm{L}$ beside it kept as another |
| the speeds marked as lines by `.plot()` and carried by `combine_fault_lines` | lines at the shaft and blade rates only |

```python
from phonometry import vibration

res = vibration.blade_pass_frequencies(3500.0, 6, n_harmonics=1, n_vanes=4)
print(res.names)
print([(p.n_lobes, p.speed_rpm) for p in res.lobe_patterns])
# ('shaft', 'BPF')
# [(2, 10500.0), (10, 2100.0)]
```

## The seventy-eight names that are gone

Everything else moved. These seventy-eight exist in no public module:

| Gone | What to write instead |
| --- | --- |
| `octavefilter`, `getansifrequencies`, `normalizedfreq` | `filters.octave_filter`, `filters.nominal_frequencies`, `filters.normalized_frequencies`. These were the original PyOctaveBand spellings, renamed in 3.1 and kept as aliases until 4.0 |
| `calculate_sensitivity` | `metrology.sensitivity`, the same 3.1 rename |
| `filter_class_compliance` | `filters.verify_filter_class` |
| `air_density_iso`, `speed_of_sound_iso` | `materials.air_density_iso10534`, `materials.speed_of_sound_iso10534`, and read the kelvin warning above |
| `speed_of_sound` | `materials.speed_of_sound_iso17497(temperature_c=...)`, the same ISO 17497-1 formula and the same number. Not `fluids.air(...).speed_of_sound`, which computes humid air by another model: 343.99 m/s against 343.20 m/s at 20 °C, as the section on the obvious fix says |
| `depth_to_pressure` | `fluids.depth_to_gauge_pressure_mpa(depth_m=...)`, which returns the same number, or `fluids.depth_to_absolute_pressure_pa` for the absolute one. Both are keyword-only and both take an optional `latitude_deg` |
| `TransmissionLossResult` | `PropagationLossResult`, with `.tl` renamed to `.pl` |
| `partial_exposure` | `vibration.daily_exposure`, called with one operation's value and duration. `partial_exposure` was a second name for the same function, and the number does not move |
| `insitu_reflection_factor`, `insitu_absorption_from_reflection`, `insitu_absorption_coefficient`, `insitu_absorption_spectrum`, `InsituAbsorptionResult` | `materials.in_situ_reflection_factor`, `materials.in_situ_absorption_from_reflection`, `materials.in_situ_absorption_coefficient`, `materials.in_situ_absorption_spectrum`, `materials.InSituAbsorptionResult`: in situ is spelled `in_situ` everywhere, as the building, emission and noise-control in-situ names already were |
| `DEFAULT_SPEED_OF_SOUND` | `materials.ISO13472_SPEED_OF_SOUND_M_S`, the 340 m/s of ISO 13472-1 Annex A. The 343 m/s the room modules default to is private now; pass `speed_of_sound=` to say which you mean |
| `OCTAVE_BANDS`, `THIRD_OCTAVE_BANDS` | `materials.RATING_OCTAVE_BANDS_HZ`, `materials.RATING_THIRD_OCTAVE_BANDS_HZ`, the bands of the ISO 11654 rating |
| `BASE_PLATE_BANDS` | `materials.BASE_PLATE_BANDS_HZ` |
| `DEFAULT_POLAR_ANGLES` | `materials.DEFAULT_POLAR_ANGLES_DEG` |
| `DEFAULT_MIC_HEIGHT`, `DEFAULT_SOURCE_HEIGHT` | `materials.DEFAULT_MICROPHONE_HEIGHT_M`, `materials.DEFAULT_SOURCE_HEIGHT_M` |
| `PART1_FREQUENCY_RANGE`, `SPOT_FREQUENCY_RANGE`, `SPOT_NARROW_BAND_RANGE` | `materials.PART1_FREQUENCY_RANGE_HZ`, `materials.SPOT_FREQUENCY_RANGE_HZ`, `materials.SPOT_NARROW_BAND_RANGE_HZ` |
| `REFERENCE_ACCELERATION` | `vibration.ACCELERATION_LEVEL_REFERENCE_M_S2`, the 1 µm/s² of ISO 1683. `vibration.REFERENCE_ACCELERATION_M_S2` is another thing, the Table 1 reference conditions of ISO 8041-1 |
| `REFERENCE_AREA` | `building.REFERENCE_AREA_M2` |
| `REFERENCE_VELOCITY` | `emission.REFERENCE_VELOCITY_M_S` |
| `DEFAULT_FREQUENCIES` | `environment.DEFAULT_FREQUENCIES_HZ` |
| `NOY_BANDS` | `aircraft.NOY_BANDS_HZ` |
| `UNDERWATER_REFERENCE_PRESSURE` | `underwater.UNDERWATER_REFERENCE_PRESSURE_PA` |
| `UNDERWATER_REFERENCE_EXPOSURE` | `underwater.UNDERWATER_REFERENCE_EXPOSURE_PA2_S`, the 1 µPa² s of ISO 1683 in Pa² s |
| `NORMALIZED_IMPEDANCE` | `emission.NORMALIZED_IMPEDANCE_PA_S_M`, the 411 Pa s/m of ISO/TS 7849 |
| `NO_TONE_AUDIBILITY` | `psychoacoustics.NO_TONE_AUDIBILITY_DB` |
| `REFERENCE_STIFFNESS` | `vibration.REFERENCE_STIFFNESS_N_M` |
| `HAV_EAV_A8`, `HAV_ELV_A8`, `WBV_EAV_A8`, `WBV_ELV_A8` | `vibration.HAV_EAV_A8_M_S2`, `vibration.HAV_ELV_A8_M_S2`, `vibration.WBV_EAV_A8_M_S2`, `vibration.WBV_ELV_A8_M_S2`, the A(8) values of Directive 2002/44/EC. `WBV_EAV_VDV` and `WBV_ELV_VDV` keep their names, because a vibration dose value has the one unit, m/s^1.75 |
| `combine_uncertainties` | `metrology.combined_standard_uncertainty`, the one root-sum-square, which takes the contributions as one sequence: `combine_uncertainties(3.0, 4.0)` is `combined_standard_uncertainty([3.0, 4.0])` |
| `combine_uncertainty` | `metrology.uncertainty_propagation`, the GUM propagation through a model, with the same `model`, `quantities` and `correlation` |
| `expanded_uncertainty` | `building.insulation_expanded_uncertainty(u, coverage, one_sided=...)`, the ISO 12999-1 function the 3.3.0 top-level name forwarded to, with the same number: `expanded_uncertainty(1.2)` and `insulation_expanded_uncertainty(1.2)` are both 2.352 dB. The GUM expanded uncertainty of a propagated result is `result.expanded(coverage)`. `environmental.expanded_uncertainty`, the ISO 1996-2 function of the same name, is `environment.environmental_expanded_uncertainty(u, coverage=...)`, 2.4 dB for the same 1.2 dB |
| `combine_linings`, `combine_subareas`, `combine_partial_exposures`, `combine_age_and_noise` | `building.combined_lining_improvement`, `building.subarea_intensity_level`, `vibration.combined_daily_exposure`, `hearing.age_and_noise_threshold`: a computation is named for what it returns |
| `air_attenuation_m` | `environment.air_power_attenuation_per_m`. The m it returns is the power attenuation coefficient of ISO 354, in 1/m, not a length |
| `attenuation_from_alpha`, `air_attenuation_coefficient` | `materials.power_attenuation_from_alpha`, the one conversion ISO 354 and ISO 17497-1 both make. Its argument is `attenuation_db_per_m`, where the two old functions named it `alpha` and `pressure_attenuation_db_per_m`. It refuses a NaN or an infinite alpha, which `attenuation_from_alpha` let through |
| `HtlanResult`, `NiptsResult` | `hearing.HTLANResult`, `hearing.NIPTSResult`: an acronym is written in capitals, as in `HMLRatingResult` |
| `AnpAircraft`, `AnpDatabase`, `AnpNpdCurves`, `AnpProfile`, `NpdLevelResult` | `aircraft.ANPAircraft`, `aircraft.ANPDatabase`, `aircraft.ANPNPDCurves`, `aircraft.ANPProfile`, `aircraft.NPDLevelResult`; the number of engines is `ANPAircraft.n_engines` |
| `HvacSpectrumResult` | `noise_control.HVACSpectrumResult` |
| `mic_calibration_factor`, `apply_mic_calibration` | `materials.microphone_calibration_factor`, `materials.apply_microphone_calibration` |
| `lab_airborne_insulation`, `lab_impact_insulation`, `LabAirborneInsulationResult`, `LabImpactInsulationResult`, `LabInsulationWarning` | `building.laboratory_airborne_insulation`, `building.laboratory_impact_insulation`, `building.LaboratoryAirborneInsulationResult`, `building.LaboratoryImpactInsulationResult`, `building.LaboratoryInsulationWarning` |
| `EnclosureResult` | `noise_control.EnclosureInsertionLossResult`, what `enclosure_insertion_loss` returns, beside `EnclosureInsulationResult` |
| `maximum_repeatability_standard_deviation`, `minimum_cumulative_duration_hours`, `minimum_phase` | `building.max_repeatability_standard_deviation`, `hearing.min_cumulative_duration_hours`, `signals.min_phase`: `max` and `min` in every public name |
| `rigid_mass_calibration_check` | `vibration.verify_rigid_mass_calibration`, with the same arguments and the same `RigidMassCalibrationResult`: it judges a measuring chain, so its verb is `verify_` |
| `satisfies_lower_requirement`, `satisfies_upper_requirement` | `building.assess_requirement_conformity(rating, expanded_uncertainty_db, required_rating, bound="minimum")` or `bound="maximum"`. The bool is its `.passes`, beside the `.margin_db` it was read from, and both formulae stay strict |
| `strong_coupling_satisfied` | `building.check_strong_coupling`, with the same arguments. The boolean array is its `.holds`, and `.passes` is every band |
| `tonal_seeking_survey` | `environment.assess_tonal_survey(levels, frequencies=frequencies)`. The boolean array is its `.prominent`, beside the `.min_level_differences` and `.level_differences` it was read from |
| `air_density_astm`, `speed_of_sound_astm` | `materials.air_density_astm_e2611`, `materials.speed_of_sound_astm_e2611`, beside `air_density_iso10534`: a standard's designation in a name is written one way |
| `sae_band_attenuation` | `aircraft.band_attenuation_arp5534`, the document it follows |
| `itu_r_468_weighting` | `electroacoustics.weighting_bs468` |

## What did not change

Most numbers. Every rename above returns what its predecessor returned, except
where this section says otherwise, and if any other result moves after you
finish the upgrade, that is a defect and it is worth
[reporting](https://github.com/jmrplens/phonometry/issues). The numbers that
did move are below. Each moved because 3.3.0 disagreed with the document it
follows, or because a default changed.

`verify_filter_class` grades every requirement of IEC 61260-1 at the bank's
input rate, not the Table 1 mask alone, and a band of a decimated bank moves by
up to 0.07 dB on white noise: the section on filter classes above says how.

| What moved | 3.3.0 | 4.0 |
| --- | --- | --- |
| Every curve, A, B, C, D, G and AU, through `WeightingFilter.filter` and `filters.weighting_filter`, which are now designed at the input rate instead of oversampled, and so every level that weights a signal through them, `signals.laeq` among them | A at 48 kHz: −2.60 dB, −7.03 dB and −10.15 dB at the 10, 16 and 20 kHz rows of IEC 61672-1 Table 3; at 16 kHz, A −13.1 dB and C −16.7 dB at the 8 kHz row; at 32 kHz, B −23.9 dB, D −17.1 dB and AU −35.9 dB at 16 kHz | −2.49 dB, −6.60 dB and −9.32 dB, the design goals within 0.02 dB; −1.11 dB and −3.01 dB at the 8 kHz row; B −8.42 dB, D −0.69 dB and AU −19.61 dB, again the design goals |
| `WeightingFilter(..., stateful=True)`, which in 3.3.0 ran A as the plain bilinear design and G with sections designed for an oversampled rate, both at the input rate, and runs the accurate design now | A at 48 kHz: −7.05 dB at the 12.5 kHz row; G at its own 10 Hz reference: −26.3 dB at 8 kHz and −36.3 dB at 1 kHz | −4.32 dB, the design goal; 0 dB at every rate |
| `verify_weighting_class` | graded the designed sections, and gave class 1 to an A weighting at 16 kHz that lost 12 dB at the 8 kHz row | grades the path a signal takes through `WeightingFilter.filter` |
| `itu_r_468_weighting`, now `electroacoustics.weighting_bs468` | ITU-R BS.468-4 Table 1 interpolated between its rows: 4.45 dB at 11.06 kHz | the curve of the network the Recommendation prints: 5.06 dB there, and at most about 0.05 dB from Table 1 at its rows |
| `sae_band_attenuation`, now `aircraft.band_attenuation_arp5534` | the saturation vapour pressure of ISO 9613-1 | the one SAE ARP 5534 prints: about 0.01 dB less over 1 km at 8 kHz and 10 kHz |
| `extended_tube_chamber` with an inlet or outlet extension | the straight section between the two side branches taken over the whole chamber length L | over L − L_a − L_b, which reproduces Bies Figure 8.20: for L = 0.5 m, an area ratio m = 16 and extensions of 0.125 m and 0.25 m, 22.7 dB at 200 Hz where it was 0.6 dB |
| `underwater.ray_trace` and `environment.atmospheric_ray_paths` at a reflection | a whole step taken through the boundary and folded back | a sub-step that ends on the boundary, so a ray that bounces lands elsewhere: one ray of a 100 m channel ends 5 km out at 9.4 m depth, where it ended at 0.3 m |
| `room.open_plan_metrics` where the STI never falls to the threshold | a distraction or privacy distance of 10¹⁵ m or more | NaN |
| `effective_kappa` and `thermal_boundary_layer_thickness` left at their default air | the five values ISO 9053-2 Annex A.3 prints | the air of IEC 61094-2 at the same state, which moves the correction in its fifth figure, as the section on `fluid=` says |
| a value that lands exactly on a limit a standard prints | judged by the last bits of its floating-point value | settled to nine decimal places first, the same on every machine |

The weighting design module is itself new in 4.0.0rc1, so three of its
changes are measured against the release candidate rather than against 3.3.0:

| What moved | 4.0.0rc1 | 4.0 |
| --- | --- | --- |
| `WeightingFilter.sos` on macOS and Windows, on glibc x86-64 without FMA, and on Linux at six of the checked designs and at rates the library is not checked at | each platform's C library rounded the design's exponentials, powers, logarithms, sines, tangents and arctangents its own way, and numpy built with clang, on macOS and Windows, fused the complex products of the bilinear transform into multiply-adds, so the A weighting at 48 kHz had a digest per platform, `43f786ffab5c4dd4` on glibc without FMA among them | no routine of the C library and no complex product of numpy's is left in the design: every platform designs the A weighting at 48 kHz to `991833ff389afe91`, and every other curve to one set of bytes too, since the roots and the sections of the cascade are the package's own arithmetic as well; on Linux the correctly rounded arctangent moves the A and C weightings at 44.1 and 88.2 kHz, the D weighting at 88.2 kHz and the G weighting at 1.5 kHz by their last bits (A at 44.1 kHz from `74d1e53f498988c5` to `dbea4b7fc4ad972b`), and of 1 399 307 (rate, curve) designs at integer rates from 100 Hz to 200 kHz, 5 864 meet a sine or a tangent glibc rounds the other way and 45 526 read a target level its arctangent changes, and can move, 50 kHz for A, B, C and D, 100 kHz for AU and 176.4 kHz for A, B and C among the common rates |
| `WeightingFilter(fs, "468").sos` at every rate, and `WeightingFilter(fs, "AU").sos` at 100 and 200 Hz | the 468 prototype's poles from LAPACK through `numpy.roots`, and the sections from SciPy's `zpk2sos`, which paired poles with zeros by numpy's complex magnitude | the correctly rounded roots of the network's exact polynomial and the design's own sections: the 468 response moves by at most 0.0072 dB at the nineteen checked rates, from 100 Hz to 192 kHz (0.000012 dB at 48 kHz, where the digest moves from `08f94c9ff182cff1` to `eee92dba5dcc41f7`), and AU by up to two units in the last place of eight coefficients at 100 Hz and one unit of six at 200 Hz |
| `WeightingFilter(fs, "B", high_accuracy=False).sos`, and the same for C and G | the complex magnitude behind the gain from numpy's own complex absolute | from the pinned `hypot`: one unit in the last place of the gain on Linux |

The ISO 3382 fiche of a one-third-octave analysis takes its single-number
reverberation time over the six bands from 400 Hz to 1250 Hz, as clause 9.1
prints, where it averaged the 500 Hz and 1 kHz bands. The ISO 10846 fiche of
an indirect determination boxes the stiffness at the lowest line ISO 10846-3
Inequality (2) admits, with a transmissibility of 0.1 or less, where it boxed
the lowest line of the sweep, inside the resonance region. The microphone fiche
writes dB(468) for the ITU-R BS.468-4 weighting, which 3.3.0 let you label
CCIR. A plot draws a band with no reading as no bar, where it drew a measured
zero. Two more are in the sections above: `installed_dynamic_stiffness` below
100 kPa·s/m², and the ISO 3746 survey positions of
`emission.measurement_positions`.

For code written against 4.0.0rc1, the `Signal` contract is the one it was,
now kept in two more places, the blocks of `read_blocks` and the waveforms
inside five results. Every other formula is untouched. 4.0 rearranged the
furniture and put the unit on the label; apart from what this section lists, it
did not recompute anything.
