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.
The one rule: imports move down one level
Section titled “The one rule: imports move down one level”In 3.3.0 the root re-exported the whole library, so from phonometry import laeq worked for almost every name. Today the root exports twenty-five things:
the twenty-one subpackages, the three classes that belong to no single domain
(Signal, ReportMetadata, PhonometryWarning) and __version__.
import phonometry
print(len(phonometry.__all__)) # 25print("laeq" in phonometry.__all__) # False
from phonometry.signals import laeq # this is the new spellingMeasured 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)Finding the new home of a name
Section titled “Finding the new home of a name”Rather than search the reference for each one, ask the installed package:
import importlibimport 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.signalsprint(whereis("reverberation_time")[0]) # phonometry.roomprint(whereis("sensitivity")[0]) # phonometry.metrologyprint(whereis("Signal")[0]) # phonometryIt walks the tree in about two seconds. When it returns several paths the
shallowest one is the canonical import: a subpackage re-exports what its own
modules publish, and that shallow path is the one the guides and the tests
use. The four names the root still publishes on its own, Signal,
PhonometryWarning, ReportMetadata and __version__, come back as
phonometry itself. An empty list means the name is in the last section of
this page.
Modules that split rather than moved
Section titled “Modules that split rather than moved”Five of the thirty modules that changed path did not move to one new address.
They were divided, and a reader who follows only the first half of the split
gets an ImportError for the rest. These are worth checking one by one, and
the private renderer package is listed with them because the same thing
happened to it:
| 3.3.0 module | Where its contents are now |
|---|---|
phonometry.impedance_tube |
materials.absorbers.impedance_tube (two-microphone transfer function), materials.absorbers.four_microphone (TransferMatrix, transfer_matrix_one_load, wave_decomposition, face_quantities, air_layer_transfer_matrix), materials.absorbers.standing_wave, and fluids |
phonometry.scattering_diffusion |
materials.diffusers.reverberation_room_scattering for the reverberation-room part (ScatteringResult, ScatteringUncertainty, BASE_PLATE_BANDS_HZ and the rest), materials.diffusers.scattering_diffusion for the nine free-field names |
phonometry.materials.porous_absorber |
materials.absorbers.porous for the bulk-material models, materials.absorbers.layered for the whole multilayer API (layered_absorber, AirLayer, MembraneLayer, PerforatedPlateLayer, MicroperforatedPlateLayer, LayeredAbsorberResult) |
phonometry.metrology.spectra |
signals.spectra, plus signals.multitaper (multitaper_psd) and signals.windows (window_metrics) |
phonometry.compliance |
filters.compliance (FilterComplianceResult, class_limits, verify_filter_class), filters.weighting_compliance (verify_weighting_class, weighting_class_limits), aircraft.measurement_system (verify_aircraft_noise_system) |
phonometry._plotting |
phonometry._plot.<domain>: the 82 renderers were split per domain, so plot_airborne_insulation is in _plot.building and plot_age_threshold in _plot.hearing. Private either way, and .plot() on the result is the supported route |
The other twenty-five moved whole, and the resolver above finds them without reading this table. Each of the first three was reachable by two paths in 3.3.0, the flat one and the one under its package, and both are gone.
Four where the obvious fix is the wrong one
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.
The impedance-tube helpers took kelvin
Section titled “The impedance-tube helpers took kelvin”air_density_iso and speed_of_sound_iso documented and consumed their
temperature in kelvin. Their successors take degrees Celsius, like the
rest of the library. The names changed, so the import fails and you will
notice, but the argument you carry over is the problem: 293.15 is a
legitimate-looking number in either unit.
from phonometry.materials import speed_of_sound_iso10534
print(round(float(speed_of_sound_iso10534(temperature_c=20.0)), 5)) # 343.28784print(round(float(speed_of_sound_iso10534(temperature_c=293.15)), 5)) # 477.13003343.29 m/s against 477.13 m/s: a 39 % error, no exception, and every absorption coefficient computed from it is wrong by a plausible-looking amount. Convert the value, do not just rename the keyword.
| 3.3.0 | 4.0 |
|---|---|
impedance_tube.air_density_iso(T_kelvin, p_kPa) |
materials.air_density_iso10534(temperature_c=T_kelvin - 273.15, static_pressure_kpa=p_kPa) |
impedance_tube.speed_of_sound_iso(T_kelvin) |
materials.speed_of_sound_iso10534(temperature_c=T_kelvin - 273.15) |
With the conversion applied both return exactly what they returned in 3.3.0, bit for bit.
GasStream took kelvin
Section titled “GasStream took kelvin”noise_control.GasStream held the inlet temperature of IEC 60534-8-3 as
inlet_temperature_k in 4.0.0rc1, in kelvin, the way Clause 5 reads it.
In 4.0 the field is inlet_temperature_c, in degrees Celsius like every other
temperature the library takes, and the conversion to the absolute temperature
Clause 5 needs happens inside. The keyword fails, so you will notice, but
450.0 is as legitimate a number in one unit as in the other: rename the
keyword and keep the number, and the gas is 273.15 K hotter. Annex A’s
example 1 at 450 K puts 91.7 dB(A) at 1 m from the pipe; the same 450 read as
degrees Celsius puts 93.0 dB(A) there, and nothing raises.
| 4.0.0rc1 | 4.0 |
|---|---|
GasStream(inlet_temperature_k=T_kelvin, ...) |
GasStream(inlet_temperature_c=T_kelvin - 273.15, ...) |
speed_of_sound is speed_of_sound_iso17497, not fluids.air()
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.2air = 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 holdThe same rename reaches underwater.sonar_equation, whose
transmission_loss parameter is now propagation_loss.
The environment moved into a dataclass
Section titled “The environment moved into a dataclass”Five entry points no longer take the ambient conditions as loose numbers. Renaming the keyword is not enough there, because the parameter is gone entirely:
| 3.3.0 | 4.0 |
|---|---|
airport_noise.event_level(..., temperature=15.0, pressure=101.325) |
event_level(..., atmosphere=AerodromeAtmosphere(temperature_c=15.0, static_pressure_kpa=101.325)) |
airport_noise.noise_contour(...) |
the same, with AerodromeAtmosphere |
rotorcraft_noise.rotorcraft_event_level(..., temperature=15.0, relative_humidity=70.0) |
rotorcraft_event_level(..., atmosphere=RotorcraftAtmosphere(temperature_c=15.0, relative_humidity_percent=70.0)) |
rotorcraft_noise.rotorcraft_noise_contour(...) |
the same, with RotorcraftAtmosphere |
outdoor_propagation.predicted_receiver_level(..., humidity=70.0) |
predicted_receiver_level(..., atmosphere=AtmosphericConditions(relative_humidity_percent=70.0)) |
The other options of these functions went into records too, the per-point rotorcraft overrides among them, and the next section maps them.
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__)# TypeErrorresult = filters.octave_filter(x, 48_000, calibration=filters.LevelCalibration(factor=2.0))print(len(result.frequencies))# 11The air of a model is one fluid=
Section titled “The air of a model is one fluid=”Twenty-two functions of 3.3.0 took the air they compute in as loose numbers:
a speed of sound and a density, for the visco-thermal models a viscosity, a
Prandtl number, a ratio of specific heats and a static pressure, and for the
thermal correction of ISO 9053-2 a specific heat and a thermal conductivity,
each with a default of its own. In 4.0 these twenty-two take one fluid=, a
fluids.Fluid that carries every property its model reads, and their loose
keywords are gone, so a call that passed one raises TypeError. Other functions
that take a speed of sound or a density, expansion_chamber among them, keep
their own keywords. Left out, fluid= is
materials.ABSORBER_AIR, which holds the defaults 3.3.0 had: 343 m/s,
1.205 kg/m³, 1.84·10⁻⁵ Pa s, a Prandtl number of 0.71, a ratio of specific heats
of 1.4 and 101.325 kPa. A call that never passed the air gives the number it
gave.
| 3.3.0 | 4.0 |
|---|---|
speed_of_sound= and air_density= on delany_bazley, miki, membrane_resonance_frequency, mass_law_transmission_loss, single_panel_transmission_loss, double_wall_transmission_loss, mass_spring_mass_resonance, ground_effect and barrier_insertion_loss |
fluid= |
speed_of_sound=, air_density= and viscosity= on layered_absorber and diffuse_field_absorption; air_density= and viscosity= on perforated_plate_impedance and microperforated_plate_impedance |
fluid= |
speed_of_sound=, air_density=, viscosity=, prandtl_number=, heat_capacity_ratio= and atmospheric_pressure= on johnson_champoux_allard, slit_helmholtz_absorber and critical_coupling_design, and the same less speed_of_sound= on helmholtz_resonator_impedance, slit_effective_properties and rectangular_duct_properties |
fluid=, whose static_pressure_pa is the pressure, in pascals as before |
air_density= on atmospheric_parabolic_equation |
fluid= |
speed_of_sound=, air_density=, specific_heat_ratio=, specific_heat_cp= and thermal_conductivity= on effective_kappa, and the same less specific_heat_ratio= on thermal_boundary_layer_thickness |
fluid=, with another default, below |
Pass the air you mean as a Fluid. fluids.air() computes one at a
temperature, a humidity and a pressure, and a Fluid built by hand carries the
numbers a book prints. A model that reads a property the fluid does not carry
raises fluids.FluidPropertyUnavailableError, naming it.
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.0print(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= |
Conditions and flags are written by name
Section titled “Conditions and flags are written by name”An ambient or medium condition or a calibration factor that carries a default,
and every public boolean flag, are keyword-only. The conditions are the
temperature, the humidity and the static pressure, the speed of sound and the
density of the medium, and the three ground factors of ISO 9613-2. The rule exists because the call site is
where the meaning is lost: air_attenuation(freqs, 20.0, 50.0, 101.325) is a
temperature, a humidity and a pressure in an order nobody remembers, and
bank.filter(x, True) says nothing about which of five flags was thrown. A
choice of method or of band set and a count (mode, method, fraction,
n, seed) are options, not conditions, and the rule leaves them where they
are.
The failure is loud, which is the point:
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 givenThat 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 givenThe 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, whosefractionis 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 = 8000x = 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 givenzoom = signals.zoom_fft(x, f_min=900.0, f_max=1100.0)print(zoom.frequencies[np.argmax(zoom.amplitude)]) # 1000.0A record you build and hand to a function is written by name the same way:
aircraft.RotorcraftHemisphere(freqs, az, po, levels) is
RotorcraftHemisphere(frequencies=freqs, azimuth_deg=az, polar_deg=po, levels=levels), and a positional call raises TypeError. A result the
library builds and another function takes whole keeps its fields where they
are, since no caller writes it field by field.
Every record you build and hand to a function takes its fields by name, not only those with an axis. These took them by position in 3.3.0 or 4.0.0rc1:
aircraft:Aerodrome,AerodynamicCoefficients,ApproachStep,DepartureStep,FlightConditionInterpolation,JetEngineCoefficients,PerformanceAircraft,PropellerEngineCoefficients,RotorcraftGround.broadcast:QuasiPeakBallistics.building:ApertureTransmissionResult,BandPath,FacadeElement,FlankingPath,HomogeneousElement,LowFrequencyProcedure,SoundReductionResult.electroacoustics:LoudspeakerDirectivity,LoudspeakerRatings,MicrophoneDirectivity,MicrophoneElectrical,MicrophoneNoise,MicrophoneOverload.emission:GradeConditions,PrecisionFieldIndicators,RoomEnvironment.environment:Barrier,DirectivityCorrection,EffectiveSoundSpeedProfile,GroundFactors,NoisePhase,PropagationGeometry,RailwayTrack,RailwayVehicle,RegulationLimits,RoadDeviceRating,RoadEmissionCoefficients,RoadSurfaceCoefficients,RoadTraffic,RollingStock,SourceEmission.filters:EQSection,FilterDesign,LevelCalibration.fluids:Fluid.hearing:ExposureResult,HMLRatingResult,SNRRatingResult,Task.io:BroadcastMetadata,SignalOrigin.materials:AbsorptionRatingResult,AirLayer,BiotWavesResult,HelmholtzResonator,MembraneLayer,MetadiffuserWell,MicroperforatedPlateLayer,PerforatedPlateLayer,PoroelasticLayer,PorousLayer,PorousMediumResult.metrology:Quantity.noise_control:DesignCriterion,DownstreamPipe,DuctElement,Expander,GasStream,LiquidPipe,LiquidStream,LiquidTrim,RegimeBoundaries,RoomToRoomResult,SourceRoom,ValveTrim.simulation:ContourPhasors,CWSource,ElasticBoundaries,ElasticRecording,ExplosionSource,ForceSource,GaussianPulse,Material,PlaneWaveSource,SignalSource.underwater:BeamFan,FluidSeabed,RayTraceResult,VolumeAbsorption,WestonSeabed.vibration:FaultFrequencyResult,FaultLine,WeightingVerification,ZoneBoundaries.
noise_control.DuctElement("Elbow", [0, 1, 2], [41, 39, 36]) is
DuctElement(label="Elbow", attenuation=[0, 1, 2], self_noise=[41, 39, 36]).
io.Signal(x, fs) is the one record that keeps its two first fields by
position: the samples and their rate are the pair every function of the
library takes that way.
One spelling per concept
Section titled “One spelling per concept”The public names had drifted into several spellings of the same quantity, and
4.0 keeps the one the majority already used. The rule for the quantities
counted in the plural is the one most of the API followed: a field or a
parameter that holds an array is frequencies, times, distances or
levels, and one that holds a single value is singular. A vectorised argument
that takes either a number or an array keeps its name. An axis carries no
unit in its name, because its unit never changes: frequencies are in
hertz, levels in decibels and the sample rate is fs on every function.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
sound_speed (control valves, silencer measurement, Weston regimes, ambient noise, FluidSeabed, ShipSourceLevelResult) |
speed_of_sound |
c= and rho= on sound_intensity, c= on the two phase-mismatch conversions, phase_mismatch() (now phase_mismatch_deg()), absorption_coefficient_uncertainty and monopole_source_level |
speed_of_sound=, density= |
speed_of_sound_m_s= on thickness_critical_frequency_product |
speed_of_sound= |
sample_rate on the FDTD SignalSource, STOIResult and impact_force_exposure_level |
fs |
sponge_width=, sponge_sides=, sponge_reflection= and .sponge_width/.sponge_sides on FDTD2D and ElasticFDTD2D |
absorbing_layer_cells=, absorbing_sides=, absorbing_layer_reflection= and .absorbing_layer_cells/.absorbing_sides, the words the run records use for the same layer, as FDTDBoundaries.absorbing_layer_cells and ElasticBoundaries.absorbing_layer_cells do; the default is still 0, no layer |
FDTD2D.plot_geometry(probes=) in metres (4.0.0rc1) |
(ix, iy) cells, as FDTDRecording.probes; each is drawn at the cell centre FDTDResult.probe_positions records, and a cell off the grid or inside an obstacle is refused as a run refuses it |
freq= on linkwitz_riley and adaptation_term_kc |
frequency= and frequencies= |
band["freq"] in the bands rows of FilterComplianceResult, WeightingComplianceResult and IntensityInstrumentComplianceResult, and between_nominals["worst_freq"] on WeightingComplianceResult |
band["frequency"] and between_nominals["worst_frequency"] |
.frequency on the results that carry a frequency axis: IntensityResult, FieldIndicators, IntensityInstrumentComplianceResult, RoomAcousticsResult, the five auditorium results, ImpedanceTubeResult, PorousMediumResult, LayeredAbsorberResult, DiffuseFieldAbsorptionResult, BiotWavesResult, SlitResonatorAbsorberResult, MetadiffuserResult, TransferMatrix, the two valve-noise results, AircraftBandAttenuation, AmbientNoiseResult, ShipTrafficSpectrum |
.frequencies |
.band_centers on the ISO 717 and ISO 11654 ratings (WeightedRatingResult, ImpactRatingResult, ExtendedWeightedRatingResult, ExtendedImpactRatingResult, AbsorptionRatingResult), .centre_frequencies on EcmaLoudness, EcmaTonality, EcmaRoughness, EcmaFluctuationStrength and MooreGlasbergLoudness, .band_frequencies on FilterComplianceResult and STOIResult, .bands_hz on RoadDeviceRating |
.frequencies, the band axis of every result |
frequency= holding an array: the flanking-transmission functions, internal_spectrum, pipe_transmission_loss, expander_noise, transfer_matrix_one_load, transfer_matrix_two_load, TransferMatrix.plot |
frequencies= |
level= and frequency= holding a band axis: apply_low_frequency_procedure, heavy_impact_octave_levels, a_weighted_maximum_impact_level, standardized_maximum_impact_level, ceiling_attenuation_class, plenum_flanking_reduction_index, single_number_average, octave_pair_averages, one_third_octave_absorption, power_injection_matrix, power_injection_clf, valve_hydrodynamic_noise, indirect_transfer_stiffness_result, and frequency_hz= on ship_source_spectrum |
levels= and frequencies= |
frequency_hz= holding an array on weighted_exposure and ocean_ambient_noise |
frequencies_hz=; the unit stays because the formulas they evaluate are printed in kHz |
.time on ZwickerLoudness, EcmaLoudness, MooreGlasbergTimeVaryingLoudness, the ECMA-418-2 tonality, roughness and fluctuation-strength results, DecayCurve, QuasiPeakResult |
.times |
.level on DecayCurve, NpdLevelResult, NoiseContourResult, RotorcraftNoiseContourResult, LowFrequencyResult, DuctPathStage, LateLateralResult, TransferStiffnessResult |
.levels |
.distance on NpdLevelResult and RotorcraftEventResult |
.distances_m |
frequencies_hz on the human-vibration instrument checks (WeightingVerification, PhaseVerification, characteristic_phase_deviation, verify_phase_response), levels_db= on operating_standard_deviation and subinterval_level |
frequencies, levels |
sound_speeds on EffectiveSoundSpeedProfile and sound_speeds= on normal_modes, ray_trace, gaussian_beams and parabolic_equation |
speeds_of_sound |
SoundSpeedProfile.sound_speed and .depth |
.speeds_of_sound and .depths |
omc_uncertainty= on sound_power_pressure and sound_energy_pressure, sigma_omc= on sound_power_anechoic, precision_uncertainty, sound_power_in_situ and sound_energy_in_situ, .sigma_omc on InSituSoundPowerResult |
sigma_omc_db |
level=, measured_level=, operational_level= on sti_from_impulse_response, stipa, sti_adjusted_for_levels and STIResult.adjusted_for_levels |
levels=, measured_levels=, operational_levels= |
.passed on AircraftSystemComplianceResult, QuasiPeakDynamicsResult, HeavyImpactSourceCheck, RigidMassCalibrationResult |
.passes, as on every other verifier |
microphone_characteristics(noise_weighting="CCIR") (3.3.0, where the weighting was a free label) and MicrophoneNoise(weighting="CCIR") (4.0.0rc1) |
noise=MicrophoneNoise(weighting="468"), the spelling weighting_filter and weighted_thd use for the ITU-R BS.468-4 curve. The weighting is "A" or "468", and microphone_characteristics refuses any other with ValueError |
atmospheric_pressure_kpa= on the ISO 9613-1 functions, atmospheric_absorption, outdoor_propagation_attenuation, AtmosphericAttenuation, AtmosphericConditions, sae_band_attenuation (now band_attenuation_arp5534), AircraftBandAttenuation, AerodromeAtmosphere, RotorcraftAtmosphere, impedance_adjustment, atmospheric_adjustment, the AnpAircraft and AnpDatabase methods, air_density_iso10534 and air_density_astm (now air_density_astm_e2611); atmospheric_pressure_pa= on enclosed_gas_stiffness and floating_floor_resonance; barometric_pressure_pa= on sound_power_intensity_precision; absolute_pressure_pa= on sea_water_density |
static_pressure_kpa= or static_pressure_pa=, the same unit |
ambient_pressure_pa= on normal_air_density |
atmospheric_pressure_pa=, the outside atmosphere beside the gauge static pressure of the duct |
environmental_ratio_from_absorption(absorption_area_m2=), running_rms_decay_time(integration_time_s=) and verify_running_rms_decay(integration_time_s=) |
absorption_area= and integration_time=, the spelling of the rest of their packages |
bending_stress(density_kg_m3=) |
density=, the spelling of the rest of vibration |
confidence= on building.insulation_coverage_factor, materials.absorption_coverage_factor, sound_absorption_coefficient_uncertainty, equivalent_area_uncertainty, practical_coefficient_uncertainty, weighted_coefficient_uncertainty, single_number_rating_uncertainty and environment.environmental_expanded_uncertainty, and UncertainValue.confidence |
coverage= and .coverage, the coverage probability of the GUM; confidence is left to the statistical confidence of an interval, as on signals.power_spectral_density |
A DecayCurve is read by name, curve.times and curve.levels, and no
longer unpacks as the pair it replaced. The FDTD solvers keep c and rho, which name the maps their
equations are written in.
A unit has one spelling too. A duration ends in _s or _hours, an angle in
_deg, a speed in kilometres per hour in _kmh and one in knots in _kt, a
decay rate in _db_per_s; _seconds, _degrees, _km_h, _knots, _db_s
and an _h that means hours appear nowhere in the public API any more.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
vibration.phase_tolerance_degrees |
vibration.phase_tolerance_deg |
ToneBurstResult.burst_seconds |
.burst_s |
wind_speed_knots= on ocean_ambient_noise and wind_noise_spectrum, and AmbientNoiseResult.wind_speed_knots |
wind_speed_kt, the spelling the aircraft speeds use |
speed_knots= on ship_source_spectrum, and ShipTrafficSpectrum.speed_knots |
speed_kt |
GasStream.molecular_mass, in kg/kmol |
GasStream.molar_mass_kg_kmol, the name the fluids catalogue gives its molar_mass_kg_mol per mole |
A word is written whole: ref is reference in every public name that
abbreviated it. SPL, SEL, SNR and RMS stay as they are, terms of art like
L_max.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
levels_ref=, background_levels_ref= and lw_ref= on sound_power_comparison and sound_energy_comparison (3.3.0), and on sound_power_in_situ and sound_energy_in_situ (4.0.0rc1) |
reference_levels=, reference_background_levels= and reference_sound_power_levels=, the last as high_frequency_sound_power_comparison spells it |
InSituSoundPowerResult.background_correction_ref, .sound_power_level_ref and .sound_energy_level_ref |
.reference_background_correction, and .sound_power_level_at_reference_conditions and .sound_energy_level_at_reference_conditions: the levels with the Annex C correction (C2, to the reference meteorological conditions), not those of the reference source |
metrology.sensitivity(ref_signal=) |
reference_signal= |
A standard’s designation is in a name only where it tells two things apart, and then it is written one way: the body joined to its number, first in a constant or a class and last in a function. Where the module already names the standard, the designation is gone.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
sae_band_attenuation |
aircraft.band_attenuation_arp5534, the document it follows |
itu_r_468_weighting |
electroacoustics.weighting_bs468 |
air_density_astm and speed_of_sound_astm, and plane_wave_frequency_range_astm (4.0.0rc1) |
materials.air_density_astm_e2611, speed_of_sound_astm_e2611 and plane_wave_frequency_range_astm_e2611, beside air_density_iso10534 |
noise_control.VDI2081_SPECTRAL_CORRECTION |
noise_control.SPECTRAL_CORRECTION: the package has no other spectral correction to tell it from, and its own text cites VDI 2081 Part 2 |
building.EN_12354_AIR |
building.EN12354_AIR |
An identifier is spelled in American English, and in situ is spelled
in_situ. A caller types every name, so center_frequency on one function
and centre_frequency on the next was a TypeError to look up. The values a
caller types are held to it too: a Literal choice, a default, the key of a
published table and a string of a published tuple of choices. catalogue
keeps its spelling: it is an American variant too, every name writes it the
same way, and it is the file format of your own catalogues. A string a source
prints keeps its print, which is why the CNOSSOS surface below is still
"optimised brushed down concrete". The closed choices of the FDTD engines
and their records are typed Literal too, a side, a recorded field, a plane
wave’s travel and a force’s axis, so a type checker refuses
free_sides="Top" before the run; nothing changes at run time.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
materials.insitu_reflection_factor, insitu_absorption_from_reflection, insitu_absorption_coefficient, insitu_absorption_spectrum, plot_insitu_geometry and InsituAbsorptionResult |
in_situ_reflection_factor, in_situ_absorption_from_reflection, in_situ_absorption_coefficient, in_situ_absorption_spectrum, plot_in_situ_geometry and InSituAbsorptionResult, as the other in-situ names of the library were already spelled |
centre_frequency on critical_bandwidth, tonal_audibility, assess_tonal_audibility and TonalAssessmentResult |
center_frequency |
centre= on room.filter_bandwidth and room.source_directivity_limit |
center= |
location="centre" on the infinite plate and beam point mobilities and impedances of vibration |
location="center" |
.unfavourable_sum on WeightedRatingResult, ImpactRatingResult and AbsorptionRatingResult |
.unfavorable_sum |
vibration.storey_fundamental_frequency(storeys), STOREY_FREQUENCY_MIN_STOREYS, STOREY_FREQUENCY_NUMERATOR_HZ, STOREY_PERIOD_COEFFICIENT_S |
vibration.story_fundamental_frequency(n_stories), STORY_FREQUENCY_MIN_STORIES, STORY_FREQUENCY_NUMERATOR_HZ, STORY_PERIOD_COEFFICIENT_S |
storeys= and the model "storeys" on fundamental_period, fundamental_frequency and estimate_fundamental_frequency |
n_stories= and the model "stories" |
draught= on underwater.monopole_source_level |
draft_m=, which says its unit as well |
procedure="aeroplane" on aircraft.effective_perceived_noise_level |
procedure="airplane", still the default |
urbanisation= on environment.outdoor_quality_objectives |
urbanization= |
vapour_pressure_pa on the IEC 60534-8-4 functions of noise_control (differential_pressure_ratio, cavitation_differential, jet_strouhal_number, stage_conditions, last_stage_differential) and on LiquidStream |
vapor_pressure_pa |
"water_vapour_mole_fraction" in the composition of fluids.air() |
"water_vapor_mole_fraction" |
building.DB_HR_NORMALISED_SPECTRA, environment.NORMALISED_RAILWAY_NOISE_SPECTRUM_DB and environment.NORMALISED_TRAFFIC_NOISE_SPECTRUM_DB |
DB_HR_NORMALIZED_SPECTRA, NORMALIZED_RAILWAY_NOISE_SPECTRUM_DB and NORMALIZED_TRAFFIC_NOISE_SPECTRUM_DB |
simulation.ALUMINIUM |
simulation.ALUMINUM |
RoadSurface.OPTIMISED_BRUSHED_DOWN_CONCRETE |
RoadSurface.OPTIMIZED_BRUSHED_DOWN_CONCRETE, whose value is still the "optimised brushed down concrete" that CNOSSOS-EU Table F-4 prints |
A word has one spelling as well. An acronym is written in capitals inside a
class name, as EPNLResult and STIResult always were; Ecma, which is the
name the organisation gives itself and not an acronym, is the exception
(EcmaLoudness). mic, lab and std are spelled out. A count is
n_<plural>, and a limit on one is min_n_ or max_n_ (min_n_records,
max_n_arrivals); a duration names its quantity before its unit, never the
unit alone (exposure_duration_years, duration_s, period_hours), with
the minute spelled out (assessment_period_minutes) because a trailing _min
is a minimum, and a class number, an axis, a number of decimals and a length counted in samples
are not counts. minimum
and maximum are written min and max in every public name, MIN and MAX
in a constant and Min and Max in a class, as numpy, SciPy, scikit-learn and
Matplotlib write them, terms of art included: the maximum and minimum levels
Lmax and Lmin are max_level and min_level (never a bare max_db), the
takt maximum of DIN 45669-1 and DIN 4150-2 is TAKT_MAX_FACTOR and the
minimum-phase reconstruction is min_phase. A confidence bound is
confidence_lower or confidence_upper. A function that reads a time
signal takes it first, as x, the name octave_filter(x, fs) and the rest
of the signal functions always used; called by position, nothing changes. The
3.3.0 top-level names among these are in the table of names that are gone.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
building.DbHrAssessment, DbHrCheck, DbHrGlobalIndexResult and DbHrRequirement, noise_control.HvacWarning, underwater.StrikeSelSpectrum |
DBHRAssessment, DBHRCheck, DBHRGlobalIndexResult, DBHRRequirement, HVACWarning, StrikeSELSpectrum |
the module building.measurement.lab_insulation |
building.measurement.laboratory_insulation; importing from building is unchanged |
HMLRatingResult.subject_h, .subject_m and .subject_l |
.subject_high, .subject_medium and .subject_low, the values per subject beside high, medium and low |
.std on TrendTestResult and StationarityTestResult, TimeDelayResult.delay_std |
.standard_deviation, .delay_standard_deviation |
StationarityTestResult.count |
.trend_statistic, the statistic of the trend test it ran |
num_points= on verify_filter_class, and FilterComplianceResult.num_points |
n_points |
AnpAircraft.num_engines and PerformanceAircraft.engines |
ANPAircraft.n_engines and PerformanceAircraft.n_engines |
blade_count= on fan_sound_power, and the blades of blade_passing_frequency |
n_blades |
count= on precision_positions |
n_positions= |
count= on circular_duct_cut_on and rectangular_duct_cut_on, and WestonRegimeBoundaries.mode_count |
n_modes |
count= on diffuser_sound_power |
n_devices= |
harmonics= on gear_mesh_frequencies and blade_pass_frequencies, and the count of FaultFrequencyResult.harmonics |
n_harmonics |
SawtoothBurstTest.burst_count |
.n_bursts |
room.MAXIMUM_DIRECTIVITY_STEP_DEG, MINIMUM_BANDWIDTH_TIME_PRODUCT, MINIMUM_DETECTOR_MULTIPLE and MINIMUM_REFERENCE_DISTANCE_M, noise_control.MAXIMUM_PASSAGE_ASPECT, MINIMUM_FLOW_RATES and MINIMUM_PRESSURE_DIFFERENCE_PA, emission.MINIMUM_BACKGROUND_MARGIN_DB |
MAX_DIRECTIVITY_STEP_DEG, MIN_BANDWIDTH_TIME_PRODUCT, MIN_DETECTOR_MULTIPLE, MIN_REFERENCE_DISTANCE_M, MAX_PASSAGE_ASPECT, MIN_FLOW_RATES, MIN_PRESSURE_DIFFERENCE_PA, MIN_BACKGROUND_MARGIN_DB |
OperatingLine.maximum_deviation, maximum_open_loop_gain and maximum_level_at_microphone on FeedbackStabilityResult, maximum_reduction_db= on end_reflection_loss, LoudspeakerCharacteristics.minimum_impedance, minimum_load_impedance on MicrophoneCharacteristics and MicrophoneElectrical, DiscretePointIntensityResult.minimum_positions, minimum_speed= on railway_source_power |
max_deviation, max_open_loop_gain, max_level_at_microphone, max_reduction=, min_impedance_ohm, min_load_impedance_ohm, min_positions, min_speed_kmh= |
building.a_weighted_maximum_impact_level, standardized_maximum_impact_level, AWeightedMaximumImpactResult and StandardizedMaximumImpactResult |
a_weighted_max_impact_level, standardized_max_impact_level, AWeightedMaxImpactResult and StandardizedMaxImpactResult: max and min in every public name, terms of art included |
room.minimum_reliable_reverberation_time and minimum_receiver_positions |
min_reliable_reverberation_time and min_receiver_positions |
PhaseDecompositionResult.minimum_phase_response |
.min_phase_response |
maximum_levels= on aircraft.event_level and noise_contour |
max_levels= |
ci_lower and ci_upper on SpectralDensityResult and MultitaperSpectralDensityResult |
confidence_lower and confidence_upper, as on MethodBSummary |
elements= on low_frequency_element_normalized_difference, and LowFrequencyElementResult.elements |
n_elements |
orders= on slit_resonance_frequencies, and the junctions of multi_junction_adjustment |
n_orders= and n_junctions |
open_microphones= on feedback_stability and open_microphone_correction, and FeedbackStabilityResult.open_microphones |
n_open_microphones |
events= on sound_energy_pressure, mean_single_event_level, sound_energy_in_situ, sound_energy_reverberation and sound_energy_comparison, and .events on SoundEnergyResult and ReverberationSoundEnergyResult |
n_events |
reflecting_planes= on measurement_positions, sound_power_pressure and sound_energy_pressure |
n_reflecting_planes= |
.positions on DiscretePointIntensityResult, and .positions, .subset_positions and .additional_positions on PartialPowerConcentration |
.n_positions, .n_subset_positions and .n_additional_positions |
RollingStock.axles, VehicleDescriptor.axles and the axles of rolling_sound_power |
n_axles |
sweep_points= on verify_weighting_class, and WeightingComplianceResult.sweep_points |
n_sweep_points |
AssumedProtectionResult.subjects |
.n_subjects |
io.AudioFileInfo.channels and .frames |
.n_channels and .n_samples, the samples per channel, as on Signal |
quadrature_points= on diffuse_field_absorption, and sum_terms= on helmholtz_resonator_impedance and rectangular_duct_properties |
n_quadrature_points= and n_sum_terms= |
repetitions= on predict_diffuser_polar_response, predicted_diffusion_spectrum, metadiffuser_diffusion_spectrum, metadiffuser_polar_response and plot_qrd_geometry, and DiffuserPolarResponse.repetitions |
n_repetitions |
cycles= and repetitions= on signals.tone_burst, ToneBurstResult.cycles and .repetitions, and cycles= on vibration.sawtooth_burst and signal_burst_indications |
n_cycles and n_repetitions |
trials= on metrology.monte_carlo, and MonteCarloResult.trials |
n_trials |
the passages of silencer_self_noise, valve_style_modifier, multihole_incipient_cavitation_ratio and uniform_passage_style_modifier, and the stages of stage_level_correction |
n_passages and n_stages |
the steps of FDTD2D.run and ElasticFDTD2D.run, and max_arrivals= on underwater.eigenrays |
n_steps and max_n_arrivals= |
simulation.ContourProbe.samples and ContourProbe(sim=...) |
.n_samples, read-only, and engine= |
record_every= and decimate= on FDTD2D.run and ElasticFDTD2D.run, by position or by name |
snapshot_every= and snapshot_decimation=, the names FDTDRecording and ElasticRecording take for the same two counts, and like them keyword-only: run(400, 10, 2) is run(400, snapshot_every=10, snapshot_decimation=2) |
fdtd_simulation(probes=..., snapshot_every=..., snapshot_decimation=...) |
fdtd_simulation(FDTDRun(..., recording=FDTDRecording(probes=..., snapshot_every=..., snapshot_decimation=...))): what an acoustic run records is one record, the recording of the run, as an elastic run’s is one ElasticRecording; a run without one records only its time axis, as before |
fdtd_simulation(c, dx, duration, sources=..., ...) and elastic_fdtd_simulation(c_p, c_s, dx, duration, sources=..., rho=..., ...) |
fdtd_simulation(FDTDRun(c=c, dx=dx, duration_s=duration, sources=..., boundaries=simulation.FDTDBoundaries(sides=..., absorbing_layer_cells=...), ...)) and elastic_fdtd_simulation(ElasticRun(c_p=c_p, c_s=c_s, dx=dx, duration_s=duration, sources=..., rho=..., ...)): a simulation is one record, with the same arguments, which takes every field by name and checks them all when it is built. duration is duration_s, and the acoustic boundaries= and absorbing_layer_cells= are now one FDTDBoundaries, as the elastic ones are one ElasticBoundaries; compute= stays on the function. A bad argument raises where the run is written, with the same class and the same words, except that a refused duration now names duration_s |
a boundaries= of elastic_fdtd_simulation that is not an ElasticBoundaries, which failed inside the run |
refused with TypeError when the ElasticRun is built |
an ElasticRecording with a malformed probe, an unknown or repeated field or a bad snapshot count, refused only when elastic_fdtd_simulation ran it; a recording= of another type, which failed inside the run |
refused when the record is built, with the same class and the same words, and a probe off the grid still refused by the run; a recording= that is not the run’s own record (FDTDRecording for an FDTDRun, ElasticRecording for an ElasticRun) raises TypeError naming it when the run is built |
sidebands= on gear_mesh_frequencies and induction_motor_frequencies, the poles, rotor_bars and slot_harmonics of induction_motor_frequencies, and lobe_orders= on blade_pass_frequencies |
n_sidebands, n_poles, n_rotor_bars, n_slot_harmonics and n_lobe_orders |
years= on hearing.nipts and htlan and on vibration.injury_risk and multiple_shock_assessment, and .years on the ISO 1999 results (NiptsResult and HtlanResult in 3.3.0) and on MultipleShockResult |
exposure_duration_years: a duration names its quantity before its unit |
environment.NoisePhase.hours and hours= on evaluation_period_level; hearing.Task.duration_range and .duration_samples, in hours |
duration_hours; .duration_range_hours and .duration_observations_hours, since a _samples ending reads as a count of samples |
seconds= on room.sweep_signal, inverse_filter and shaped_sweep_signal, on electroacoustics.synchronized_sweep_signal and swept_sine_distortion, on signals.noise_signal and on speech.stipa_signal; duration= on room.image_source_rir, SweptSineDistortionResult.duration, and io.Signal.duration and io.AudioFileInfo.duration (4.0.0rc1); flat_duration=, leading_duration= and trailing_duration= on materials.adrienne_window, StationarityTestResult.segment_duration and PileStrikeResult.pulse_duration |
duration_s, the spelling the other durations in seconds already had, and flat_duration_s=, leading_duration_s=, trailing_duration_s=, .segment_duration_s and .pulse_duration_s: a duration ends in its unit |
hours= on environment.lden and ldn |
period_hours=, which is now keyword-only |
assessment_period_min= on environment.impulse_prominence, and ImpulseProminenceResult.assessment_period_min |
assessment_period_minutes: a trailing _min reads as a minimum (f_min), so the minute is spelled out, as the hour is |
ReportMetadata.source_positions and .receiver_positions |
.n_source_positions and .n_receiver_positions |
signal_in= on loudness_ecma, tonality_ecma, roughness_ecma, fluctuation_strength_ecma and fluctuation_strength; signal= on loudness_moore_glasberg_time, on the distortion and noise measurements of electroacoustics (thd, thd_plus_noise, sinad, weighted_thd, harmonic_analysis, harmonic_distortion, dynamic_range, idle_channel_noise, modulation_distortion, difference_frequency_distortion, total_difference_frequency_distortion, dynamic_intermodulation_distortion), on impulsive_sound_adjustment and sound_pressure_level_history, on the human-vibration functions (running_rms, mtvv, vibration_dose_value, motion_sickness_dose_value, crest_factor, apply_weighting, apply_band_limiting) and on room.plot_excitation |
x |
tone_freq= on tone_to_noise_ratio and prominence_ratio |
tone_frequency=, which, like resolution_hz=, is now keyword-only |
A choice reads the same everywhere it is offered. A band set is the integer
fraction that OctaveFilterBank, decay_curve and sound_intensity already
took, 3 for one-third octaves and 1 for octaves; the words "third",
"third-octave", "one-third-octave" and "octave" are refused, and a table
read by band set is keyed by the same integer. A free, a diffuse and a
pressure field are written "free", "diffuse" and "pressure". A frequency
weighting is chosen by weighting, and leaving the signal unweighted is
written "Z" wherever that is offered: on the sound-level weightings it is the
Z-weighting of IEC 61672-1, and elsewhere it is the response the standard
leaves unweighted, such as the band limitation alone of the DIN 45669-1
vibration meter.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
band= on field_incidence_correction, mass_law_transmission_loss, single_panel_transmission_loss, double_wall_transmission_loss, orthotropic_transmission_loss, short_pulse_mean_square_force, tapping_force_spectrum, covering_improvement, a_weighted_maximum_impact_level and cylindrical_shell_modal_density, and .band on TappingForceResult and AWeightedMaximumImpactResult |
fraction= and .fraction, 3 or 1 |
bands= on weighted_rating, weighted_impact_rating, SoundReductionResult.rating, facade_sound_reduction, normalized_flanking_level_difference, normalized_flanking_impact_level, calculated_sound_reduction_index, reciprocity_impact_level, in_situ_element, detailed_airborne_prediction and detailed_impact_prediction |
fraction=; None still reads the band set from the values where it did |
band_type= on sound_power_intensity, sound_power_intensity_points, position_count_factor and determination_standard_deviation |
fraction= |
bandwidth= on tapping_machine_force_level_estimate |
fraction= |
building.HEAVY_IMPACT_A_WEIGHTING["third"] and ["octave"] |
[3] and [1] |
"free-field" and "diffuse-field" on hearing.reference_threshold, and in hearing.FIELDS |
"free" and "diffuse" |
curve= on filters.weighting_filter and WeightingFilter, WeightingFilter.curve and WeightingComplianceResult.curve |
weighting= and .weighting |
weighted= on broadcast.quasi_peak_meter, and QuasiPeakResult.weighted |
weighting="468" (the default) or weighting="Z", and .weighting |
weighting=None on signals.ln_levels and sel |
weighting="Z", now the default |
building.PathContribution.fraction, the share of the transmitted energy a path carries |
.energy_fraction, so that fraction names only a band set |
building.DetailedAirborneResult.fractions and DetailedImpactResult.fractions, the share of the energy each path carries in each band |
.energy_fractions |
Every public name has one address
Section titled “Every public name has one address”A handful of names could be imported from a second module in 3.3.0 or 4.0.0rc1, or from a module that listed something its package did not publish, and the ANP database put a private name in two constructors. Each name has a single address now, the one the resolver above returns, and none is private:
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
vibration.partial_exposure |
vibration.daily_exposure, the function it was a second name for. Called with the value and the duration of one operation, it returns that operation’s partial exposure Ai(8), and the number does not move |
the ISO 717 ratings listed by building.measurement.insulation: weighted_rating, weighted_impact_rating, their _extended forms, weighted_impact_improvement, impact_improvement_adaptation_term and the four rating results |
building.weighted_rating and the rest, defined in building.measurement.ratings |
LowFrequencyProcedure listed by building.measurement.insulation |
building.LowFrequencyProcedure, defined in building.measurement.low_frequency |
the ISO 12354-1 Annex D linings listed by building.prediction.resilient_layers: lining_improvement, lining_improvement_in_situ, lining_resonance_frequency, weighted_lining_improvement, LiningImprovementResult |
building.lining_improvement and the rest, defined in building.prediction.linings |
emission.DeclarationForm; Grade and Surface listed by emission.sound_power; EQFilterType listed by filters.equalizer (metrology.equalizer in 3.3.0) |
nothing to import: no type alias is public. Pass the string the parameter takes, form="single-number" for instance, and the API reference shows each parameter’s Literal[...] where the alias used to be |
BASIC_METHOD_MAX_CREST_FACTOR listed by vibration.human.exposure |
not published. vibration.crest_factor warns above 9, the crest factor up to which ISO 2631-1 6.2.2 holds the basic method sufficient |
REFERENCE_IMPEDANCE, REFERENCE_AREA and REFERENCE_SOUND_POWER of emission.vibration_sound_power, a module with no __all__ whose package never published them |
not published. The 400 N·s/m³ and the 1 m² are the defaults of reference_impedance= and reference_area= in emission.radiated_sound_power_level, and the 1 pW is metrology.REFERENCE_VALUES["gas"]["sound_power"].value |
AnpAircraft(..., _database=db) and aircraft._database |
ANPAircraft(..., database=db) and aircraft.database, still left out of the repr and of comparisons |
AnpDatabase(..., performance=...) (4.0.0rc1) |
no performance=, whose type nothing published: aircraft.load_anp_database reads the performance tables of an export, and a database built by hand flies fixed-point profiles |
from phonometry import building, vibration
# ISO 5349-2 E.3: the brush-saw's partial exposure, 4.6 m/s² for 2 hprint(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# FalseA 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 roadprint(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.01A 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.18A name says the quantity it holds
Section titled “A name says the quantity it holds”A name that put _db after words that only qualify it (corrected_db,
floor_db, threshold_db, mean_db) said the unit of a number and never
what the number is. Each now carries the noun of what it holds. A level takes
level or levels and then loses its _db by the rule of the section above
(threshold_level, corrected_levels, emission_levels), a level
difference takes its own noun (floor_level_difference, mean_attenuation,
min_isolation), and any other quantity keeps _db after its noun
(fixture_uncertainty_db, lower_tolerance_db, prominence_limit_db). A
name without decibels takes the noun of its quantity too: a tolerance is a
bound a value has to stay within, and no value is held to the ± 50 % that
ISO 4866 D.2 calls typical of an empirical prediction of a building’s
fundamental frequency, so it is named an error. Most of these names are newer
than 4.0.0rc1; the ones that shipped are these.
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
psychoacoustics.ToneAssessment.criterion_db |
prominence_limit_db |
signals.WindowMetricsResult.highest_sidelobe_db |
highest_sidelobe_level |
broadcast.KWeightingResponse.shelf_db and highpass_db |
shelf_magnitude_db and highpass_magnitude_db, beside magnitude_db |
signals.LifterResult.liftered_db |
liftered_spectrum_db, beside spectrum_db |
operating_db= on emission.total_standard_deviation |
sigma_omc_db=, the name every sound power function gives the standard deviation of the operating and mounting conditions |
polar_db of electroacoustics.MicrophoneCharacteristics and electroacoustics.LoudspeakerCharacteristics |
polar_response_db |
vibration.EMPIRICAL_FREQUENCY_TOLERANCE |
EMPIRICAL_FREQUENCY_ERROR, the same 0.5, beside the empirical_frequency_bounds that applies it |
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.5A 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 TrueAnd 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 .plot() takes the axes first
Section titled “Every .plot() takes the axes first”Every result’s .plot() now reads plot(ax=None, *, ...): the axes first,
and every other argument by name, language included. Three did not start
with the axes in 3.3.0, so plot(ax) on them handed the axes to the wrong
parameter:
| 3.3.0 | 4.0 |
|---|---|
LoudspeakerCharacteristics.plot("impedance", ax) |
.plot(ax, quantity="impedance") |
MicrophoneCharacteristics.plot("noise", ax) |
.plot(ax, quantity="noise") |
TransferMatrix.plot(f, rho_c, ax) |
.plot(ax, frequencies=f, characteristic_impedance=rho_c) |
Six results that are newer than 3.3.0 took language by position in
4.0.0rc1: the four hearing-protector ratings and the two low-frequency
intensity results. plot(ax, "es") on those is plot(ax, language="es")
now, as it is everywhere else.
The public plot_* helpers, which draw a device or a geometry rather than a
result, share one shape now as well: what they draw by position, and the
axes, the language and the style keywords by name,
plot_x(<data>, *, ax=None, ..., language="en", **kwargs). Seventeen took the
axes after their data and six took them first. plot_silencer_geometry also
took every dimension as a keyword of its own; it takes the kind and the
geometry a ReactiveSilencerResult keeps now, the dimensions in one mapping
under the same keys, so the drawing reads like the result:
| 3.3.0 or 4.0.0rc1 | 4.0 |
|---|---|
vibration.plot_plate_geometry(0.8, 0.6, ax), environment.plot_barrier_geometry(ax, source_height=...) and the other twenty-one public plot_* helpers |
plot_plate_geometry(0.8, 0.6, ax=ax), plot_barrier_geometry(ax=ax, source_height_m=...) |
noise_control.plot_silencer_geometry("expansion chamber", ax, length=0.3, chamber_area=0.04, pipe_area=0.01) |
plot_silencer_geometry("expansion chamber", {"length": 0.3, "chamber_area": 0.04, "pipe_area": 0.01}, ax=ax) |
A multi-panel .plot() returns a tuple of axes
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.5check = materials.check_base_plate_scattering([0.02] * len(materials.BASE_PLATE_BANDS_HZ))print(check.passes, check.exceeded_frequencies.size)# True 0try: bool(check)except TypeError as error: print(type(error).__name__)# TypeErrorThe 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 npfrom phonometry import filters
result = filters.octave_filter(np.zeros(8000) + 1e-6, 8000, fraction=3)print(len(result.frequencies), result.bands)# 25 Nonebands 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 npfrom 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.88The 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.]A record’s fields are required
Section titled “A record’s fields are required”Several records carried fields that defaulted to None, so that a result
built by hand from a few of its numbers would still construct. Every reader
then had to ask whether the field was there: the fiche refused a bare rating
only once a report was asked for, and a plot of the geometry raised that the
result “does not retain its geometry”. The fields are required now, and a
record built without one, or with None for one (dataclasses.replace
included), raises TypeError naming it.
| Record | Required now |
|---|---|
building.AirborneInsulationResult |
l1, l2, t2, t0 |
building.ImpactInsulationResult |
li, t2, t0 |
building.WeightedRatingResult, building.ImpactRatingResult |
frequencies, measured, shifted_reference |
building.ExtendedWeightedRatingResult, building.ExtendedImpactRatingResult |
frequencies, measured |
building.ApertureTransmissionResult |
depth, now the fourth field; and width_m for a slit or radius for a circular aperture |
building.FacadePredictionResult |
elements, now the sixth field |
emission.IntensityResult |
spacing_m, keyword-only |
environment.BarrierInsertionLoss |
source_height_m, barrier_distance, barrier_height_m, receiver_distance, receiver_height_m, keyword-only |
psychoacoustics.ZwickerLoudness |
field ("free" or "diffuse"), now the fourth field, before n5 |
room.OpenPlanResult |
positions_m, the distances the metrics were fitted on |
materials.LayeredAbsorberResult |
layers, the stack the prediction was solved for |
materials.DiffuserPolarResponse |
well_width and n_repetitions, keyword-only; depths stays optional, because a response predicted from an explicit reflection has none |
materials.MetadiffuserResult |
wells, depth_m and period_m, the panel the reflection was solved for, keyword-only |
materials.SlitResonatorAbsorberResult |
resonators, slit_height_m, lattice_step_m and period_m, the panel the prediction was solved for, keyword-only |
materials.ImpedanceTubeResult |
spacing_m and x1, the microphone spacing and the distance from the sample to the farther microphone, which the reduction cannot run without, keyword-only; diameter_m stays optional, because it need not be supplied |
materials.InSituAbsorptionResult |
source_height_m and microphone_height_m, the set-up the absorption was measured with, keyword-only |
vibration.JunctionTransmissionResult |
thickness1_m and thickness2_m, the plates of the junction, keyword-only |
noise_control.ReactiveSilencerResult |
plane_wave_limit, and exactly one of geometry (a named device) and chain (a SilencerChain); resonances, geometry, plane_wave_limit and chain are keyword-only |
simulation.FDTDResult and simulation.ElasticFDTDResult take two more
fields, after the others: snapshot_decimation, every how many cells a
snapshot keeps along each axis (1 for every cell, as before), and
provenance, the simulation.RunProvenance of where the run stepped. A
result built by hand passes both, and leaving one out raises TypeError
naming it; the results the simulation functions return carry both already. A
RunProvenance built by hand passes every field, phonometry_version, the
version of the phonometry that ran the steps, among them.
filters.WeightingFilter(..., high_accuracy=None) used to select the
default. high_accuracy is a plain bool now, True by default, and None
raises TypeError rather than being read as false, which would pick the plain
design.
building.CeilingAttenuationResult.rounded was a field the caller passed in.
It is read from measured now, rounded to the nearest integer as ASTM E413
clause 5.2 asks (the clause leaves a half open, and the library rounds
it up), so it cannot disagree with the data;
leave it out when building the record by hand.
Waveforms inside results come back as the Signal they came from
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.
A block stream yields Signal blocks
Section titled “A block stream yields Signal blocks”io.read_blocks is newer than 3.3.0, and in 4.0.0rc1 it yielded bare float64
arrays. It now yields a Signal per block, carrying the rate, the
calibration, the channel labels and the provenance io.read gives, and it
takes the same calibration_factor= and reads the same sidecar. Two things
change for a loop written against the release candidate. A block from a
calibrated file reaches the filters and the level functions in pascals, so a
calibration_factor applied by hand on top of it counts twice. And
arithmetic on a block, or on what a filter returns for one, goes through
np.asarray, as it does for any Signal.
Published tables refuse writes
Section titled “Published tables refuse writes”Every table the library publishes at module level is read-only in 4.0. In
3.3.0 published tables were plain dictionaries and published arrays took
in-place arithmetic, so a line such as REFERENCE_CURVE[500] = 0.9 or
BAND_IMPORTANCE *= 2 changed the number for every caller that ran after it
in the same process, and nothing raised. The dictionaries are now
types.MappingProxyType, including the ones nested inside another table, and
the arrays have their writeable flag cleared. Reading is unchanged; writing
raises TypeError on a table and ValueError on an array.
Code that adjusted a published table has to copy it first:
from phonometry import roomfrom phonometry.materials.absorbers import REFERENCE_CURVE
curve = dict(REFERENCE_CURVE)curve[4000] = 1.0curves = room.NC_CURVE_LEVELS.copy()curves[0, 0] = 0.0print(REFERENCE_CURVE[4000], curve[4000], curves[0, 0], room.NC_CURVE_LEVELS[0, 0])# 0.9 1.0 0.0 78.0A 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.0samples = np.zeros(4)signal = io.Signal(samples, fs=48_000)samples[0] = 1.0measured = np.array([1.0, 0.5, 0.25, 0.125])response = room.ImpulseResponseResult(ir=measured, fs=48_000, method="farina")measured[0] = 0.0edited = nc.levels.copy()edited[0] = 62.0print(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 TrueThe 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"))# estimatedprint(ear.converted["youngs_modulus_max_pa"], ear.is_derived("youngs_modulus_max_pa"))# ('3e5', 'psi') FalseThe 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.6A 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 1A 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 Truetry: dataclasses.replace(check, limit_db=10.0)except TypeError as error: print(type(error).__name__)# TypeErrorcalibration = 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.2try: dataclasses.replace(gap, passes=False)except TypeError as error: print(type(error).__name__)# TypeErrorwider = dataclasses.replace(gap, readings_mm=(5.0, 5.1, 5.6, 5.1))print(wider.uniform, wider.passes)# False Falsebank = 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 FalseA 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.AutomaticThresholdResultandSweepThresholdResult: 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 thanround(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)# Falseprint(building.tapping_force_spectrum(bands, 1.0e6, 100.0).over_critical)# Truetry: dataclasses.replace(force, impedance=100.0)except ValueError as error: print("cut_off_frequency" in str(error))# TrueA 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 phonometryfrom 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# TrueA 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 choice is matched as it is written
Section titled “A choice is matched as it is written”A parameter or a record field typed with a Literal of its options, whose
code cleaned the text up before it checked it, now takes the spellings that
Literal lists, and only those. Before 4.0, 198 of them folded the case,
stripped the spaces, swapped _, - and spaces, mapped an alias of their own
or made a text of any value with str() before they looked the choice up, so
a call a type checker refused ran all the same:
filters.WeightingFilter(48000, "a"), filters.time_weighting(x, fs, mode="FAST"), vibration.guide_values("residential", edition=1999). Two
more read one option and took any other value for the second: the
onset_rate_method of environment.detect_onsets and
environment.impulsive_sound_adjustment fitted anything but "upper_half"
as least squares. In 4.0 such a call raises ValueError, or TypeError for
a value that is not text, and the fix is to write the option as its Literal
lists it. The aliases a
Literal lists on purpose still work: "docente" for "educational" in
building.db_hr_facade_requirement, "dnt_w" for "r_w" in
building.single_number_uncertainty. Files the library reads, such as an ANP
database, are still read whatever case they write their words in.
from phonometry import filters
try: filters.WeightingFilter(48000, "a")except ValueError as refusal: print(type(refusal).__name__)print(filters.WeightingFilter(48000, "A").weighting)# ValueError# AEach 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 tempfilefrom 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 fileA 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)]The seventy-eight names that are gone
Section titled “The seventy-eight names that are gone”Everything else moved. These seventy-eight exist in no public module:
| Gone | What to write instead |
|---|---|
octavefilter, getansifrequencies, normalizedfreq |
filters.octave_filter, filters.nominal_frequencies, filters.normalized_frequencies. These were the original PyOctaveBand spellings, renamed in 3.1 and kept as aliases until 4.0 |
calculate_sensitivity |
metrology.sensitivity, the same 3.1 rename |
filter_class_compliance |
filters.verify_filter_class |
air_density_iso, speed_of_sound_iso |
materials.air_density_iso10534, materials.speed_of_sound_iso10534, and read the kelvin warning above |
speed_of_sound |
materials.speed_of_sound_iso17497(temperature_c=...), the same ISO 17497-1 formula and the same number. Not fluids.air(...).speed_of_sound, which computes humid air by another model: 343.99 m/s against 343.20 m/s at 20 °C, as the section on the obvious fix says |
depth_to_pressure |
fluids.depth_to_gauge_pressure_mpa(depth_m=...), which returns the same number, or fluids.depth_to_absolute_pressure_pa for the absolute one. Both are keyword-only and both take an optional latitude_deg |
TransmissionLossResult |
PropagationLossResult, with .tl renamed to .pl |
partial_exposure |
vibration.daily_exposure, called with one operation’s value and duration. partial_exposure was a second name for the same function, and the number does not move |
insitu_reflection_factor, insitu_absorption_from_reflection, insitu_absorption_coefficient, insitu_absorption_spectrum, InsituAbsorptionResult |
materials.in_situ_reflection_factor, materials.in_situ_absorption_from_reflection, materials.in_situ_absorption_coefficient, materials.in_situ_absorption_spectrum, materials.InSituAbsorptionResult: in situ is spelled in_situ everywhere, as the building, emission and noise-control in-situ names already were |
DEFAULT_SPEED_OF_SOUND |
materials.ISO13472_SPEED_OF_SOUND_M_S, the 340 m/s of ISO 13472-1 Annex A. The 343 m/s the room modules default to is private now; pass speed_of_sound= to say which you mean |
OCTAVE_BANDS, THIRD_OCTAVE_BANDS |
materials.RATING_OCTAVE_BANDS_HZ, materials.RATING_THIRD_OCTAVE_BANDS_HZ, the bands of the ISO 11654 rating |
BASE_PLATE_BANDS |
materials.BASE_PLATE_BANDS_HZ |
DEFAULT_POLAR_ANGLES |
materials.DEFAULT_POLAR_ANGLES_DEG |
DEFAULT_MIC_HEIGHT, DEFAULT_SOURCE_HEIGHT |
materials.DEFAULT_MICROPHONE_HEIGHT_M, materials.DEFAULT_SOURCE_HEIGHT_M |
PART1_FREQUENCY_RANGE, SPOT_FREQUENCY_RANGE, SPOT_NARROW_BAND_RANGE |
materials.PART1_FREQUENCY_RANGE_HZ, materials.SPOT_FREQUENCY_RANGE_HZ, materials.SPOT_NARROW_BAND_RANGE_HZ |
REFERENCE_ACCELERATION |
vibration.ACCELERATION_LEVEL_REFERENCE_M_S2, the 1 µm/s² of ISO 1683. vibration.REFERENCE_ACCELERATION_M_S2 is another thing, the Table 1 reference conditions of ISO 8041-1 |
REFERENCE_AREA |
building.REFERENCE_AREA_M2 |
REFERENCE_VELOCITY |
emission.REFERENCE_VELOCITY_M_S |
DEFAULT_FREQUENCIES |
environment.DEFAULT_FREQUENCIES_HZ |
NOY_BANDS |
aircraft.NOY_BANDS_HZ |
UNDERWATER_REFERENCE_PRESSURE |
underwater.UNDERWATER_REFERENCE_PRESSURE_PA |
UNDERWATER_REFERENCE_EXPOSURE |
underwater.UNDERWATER_REFERENCE_EXPOSURE_PA2_S, the 1 µPa² s of ISO 1683 in Pa² s |
NORMALIZED_IMPEDANCE |
emission.NORMALIZED_IMPEDANCE_PA_S_M, the 411 Pa s/m of ISO/TS 7849 |
NO_TONE_AUDIBILITY |
psychoacoustics.NO_TONE_AUDIBILITY_DB |
REFERENCE_STIFFNESS |
vibration.REFERENCE_STIFFNESS_N_M |
HAV_EAV_A8, HAV_ELV_A8, WBV_EAV_A8, WBV_ELV_A8 |
vibration.HAV_EAV_A8_M_S2, vibration.HAV_ELV_A8_M_S2, vibration.WBV_EAV_A8_M_S2, vibration.WBV_ELV_A8_M_S2, the A(8) values of Directive 2002/44/EC. WBV_EAV_VDV and WBV_ELV_VDV keep their names, because a vibration dose value has the one unit, m/s^1.75 |
combine_uncertainties |
metrology.combined_standard_uncertainty, the one root-sum-square, which takes the contributions as one sequence: combine_uncertainties(3.0, 4.0) is combined_standard_uncertainty([3.0, 4.0]) |
combine_uncertainty |
metrology.uncertainty_propagation, the GUM propagation through a model, with the same model, quantities and correlation |
expanded_uncertainty |
building.insulation_expanded_uncertainty(u, coverage, one_sided=...), the ISO 12999-1 function the 3.3.0 top-level name forwarded to, with the same number: expanded_uncertainty(1.2) and insulation_expanded_uncertainty(1.2) are both 2.352 dB. The GUM expanded uncertainty of a propagated result is result.expanded(coverage). environmental.expanded_uncertainty, the ISO 1996-2 function of the same name, is environment.environmental_expanded_uncertainty(u, coverage=...), 2.4 dB for the same 1.2 dB |
combine_linings, combine_subareas, combine_partial_exposures, combine_age_and_noise |
building.combined_lining_improvement, building.subarea_intensity_level, vibration.combined_daily_exposure, hearing.age_and_noise_threshold: a computation is named for what it returns |
air_attenuation_m |
environment.air_power_attenuation_per_m. The m it returns is the power attenuation coefficient of ISO 354, in 1/m, not a length |
attenuation_from_alpha, air_attenuation_coefficient |
materials.power_attenuation_from_alpha, the one conversion ISO 354 and ISO 17497-1 both make. Its argument is attenuation_db_per_m, where the two old functions named it alpha and pressure_attenuation_db_per_m. It refuses a NaN or an infinite alpha, which attenuation_from_alpha let through |
HtlanResult, NiptsResult |
hearing.HTLANResult, hearing.NIPTSResult: an acronym is written in capitals, as in HMLRatingResult |
AnpAircraft, AnpDatabase, AnpNpdCurves, AnpProfile, NpdLevelResult |
aircraft.ANPAircraft, aircraft.ANPDatabase, aircraft.ANPNPDCurves, aircraft.ANPProfile, aircraft.NPDLevelResult; the number of engines is ANPAircraft.n_engines |
HvacSpectrumResult |
noise_control.HVACSpectrumResult |
mic_calibration_factor, apply_mic_calibration |
materials.microphone_calibration_factor, materials.apply_microphone_calibration |
lab_airborne_insulation, lab_impact_insulation, LabAirborneInsulationResult, LabImpactInsulationResult, LabInsulationWarning |
building.laboratory_airborne_insulation, building.laboratory_impact_insulation, building.LaboratoryAirborneInsulationResult, building.LaboratoryImpactInsulationResult, building.LaboratoryInsulationWarning |
EnclosureResult |
noise_control.EnclosureInsertionLossResult, what enclosure_insertion_loss returns, beside EnclosureInsulationResult |
maximum_repeatability_standard_deviation, minimum_cumulative_duration_hours, minimum_phase |
building.max_repeatability_standard_deviation, hearing.min_cumulative_duration_hours, signals.min_phase: max and min in every public name |
rigid_mass_calibration_check |
vibration.verify_rigid_mass_calibration, with the same arguments and the same RigidMassCalibrationResult: it judges a measuring chain, so its verb is verify_ |
satisfies_lower_requirement, satisfies_upper_requirement |
building.assess_requirement_conformity(rating, expanded_uncertainty_db, required_rating, bound="minimum") or bound="maximum". The bool is its .passes, beside the .margin_db it was read from, and both formulae stay strict |
strong_coupling_satisfied |
building.check_strong_coupling, with the same arguments. The boolean array is its .holds, and .passes is every band |
tonal_seeking_survey |
environment.assess_tonal_survey(levels, frequencies=frequencies). The boolean array is its .prominent, beside the .min_level_differences and .level_differences it was read from |
air_density_astm, speed_of_sound_astm |
materials.air_density_astm_e2611, materials.speed_of_sound_astm_e2611, beside air_density_iso10534: a standard’s designation in a name is written one way |
sae_band_attenuation |
aircraft.band_attenuation_arp5534, the document it follows |
itu_r_468_weighting |
electroacoustics.weighting_bs468 |
What did not change
Section titled “What did not change”Most numbers. Every rename above returns what its predecessor returned, except where this section says otherwise, and if any other result moves after you finish the upgrade, that is a defect and it is worth reporting. 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.