Skip to content

Upgrading from 3.3 to 4.0

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.

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__.

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:

from phonometry import filters
print(filters.nominal_frequencies(1).labels)

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

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.

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

Section titled “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.

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.

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.

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()

Section titled “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.

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

Section titled “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.

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.

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.

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

Section titled “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.

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

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.

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). 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

Section titled “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 from installed_dynamic_stiffness(20e6, 50.0), Formula 6 with its second term dropped, and 4.0 raises and asks for .

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 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=

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:

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.

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 *:

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)
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.

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

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
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

Section titled “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.

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

Section titled “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 and its grade 2 bound MAX_K3, GRADE_2_MAX_K3
sound_reduction_index_db on environment.airborne_insulation_rating sound_reduction_index
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 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
-31.5
from phonometry import emission, signals
print(round(signals.window_metrics("hann").highest_sidelobe_level, 1))
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

Section titled “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].

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

Section titled “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.

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 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

Section titled “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

Section titled “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 floats 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

Section titled “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

Section titled “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

Section titled “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.

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

Section titled “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.

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

Section titled “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
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:

ax = result.plot()

Other answers that were tuples are records

Section titled “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)
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

Section titled “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)
from phonometry import vibration
lower, upper = vibration.weighting_tolerance_percent("Wk", [16.0])
print(lower, upper)
# [-11.] [12.]

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

Section titled “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.

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.

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:

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

Section titled “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:

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

Section titled “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.

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
layer.natural_frequency(mass_per_area=...) layer.natural_frequency(mass_per_area_kg_m2=...); a layer that holds only also takes airflow_resistivity_pa_s_m2= and gas_stiffness_n_m3=, and raises ValueError without the first

Hopkins Table A3 prints , 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.

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

Section titled “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.

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

Section titled “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.

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

Section titled “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.

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

Section titled “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.

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

Section titled “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.
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

Section titled “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 UserWarnings, 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
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

Section titled “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 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.

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

Section titled “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

Section titled “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.

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

Section titled “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
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

Section titled “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

Section titled “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

Section titled “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 named by , its speed positive n_lobes and speed_rpm negative, and a pattern of 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
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)]

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

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. 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.