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, ten 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 three places the obvious fix is the wrong one, and one of those three changes a number without raising anything.

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

import phonometry

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

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

Measured across the whole surface, 872 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

_, _, _, labels = filters.nominal_frequencies(1)
print(labels)

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

import importlib
import pkgutil

import phonometry


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


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

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

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

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.

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

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

from phonometry.materials import speed_of_sound_iso10534

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

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

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

The ISO 17497-1 helper of the same name took degrees Celsius, so no conversion is needed there. The catch is the replacement. fluids.air() uses a fuller model of the medium than the ISO 17497-1 one-liner, and at 20 °C it answers 343.99 m/s where the old helper answered 343.20 m/s. That is small, and it is not nothing if you are reproducing a measurement made with the old number. ISO 17497-1 clause 8 prints the formula if you need that clause exactly.

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

from phonometry.underwater.propagation.closed_form import propagation_loss

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

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

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

The per-point rotorcraft overrides went the same way: bank_angle and path_angle are now RotorcraftTrackState(bank_angle_deg=..., path_angle_deg=...).

from phonometry.aircraft.airport_noise import AerodromeAtmosphere

atmosphere = AerodromeAtmosphere(temperature_c=15.0, atmospheric_pressure_kpa=101.325)
print(atmosphere.temperature_c, atmosphere.atmospheric_pressure_kpa)

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.

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:

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

Two rules made 37 signatures keyword-only. A condition or an option that carries a default is written by name, and every public boolean flag is keyword-only. Both exist 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.

The failure is loud, which is the point:

import numpy as np

from phonometry.signals import leq

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

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

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

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

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.

times, levels = decay_curve(ir, fs) still unpacks the decay curve, in the same order. The FDTD solvers keep c and rho, which name the maps their equations are written in.

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:

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 five verify_* functions returned dict[str, Any] and now return a frozen dataclass, like every other result in the library. Two public wrappers that existed only to package that dictionary went with the change, since the verifier now returns the object itself.

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.

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, like every other computation in the library.

import numpy as np
from phonometry import filters

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

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

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

ax = result.plot()

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:

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

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

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

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

from phonometry.materials.absorbers import REFERENCE_CURVE
from phonometry.speech.sii import BAND_IMPORTANCE

curve = dict(REFERENCE_CURVE)
curve[4000] = 1.0
weights = BAND_IMPORTANCE.copy()
weights[0] = 0.0
print(REFERENCE_CURVE[4000], curve[4000], weights[0], BAND_IMPORTANCE[0])
# 0.9 1.0 0.0 0.0083

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

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.

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

from phonometry import solids

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

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

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

from phonometry import materials

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

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:

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'})

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. A verdict for edition="1995" is unchanged.

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"))
# 2 1

Everything else moved. These ten exist in no public module:

Numbers. The conformance report is the same 995 checks against the same standards with the same expected values it had before the reorganisation, and every rename above was checked to return what its predecessor returned. If a result moves after you finish the upgrade, that is a defect and it is worth reporting.

One verdict is the exception, and the section on filter classes above says how: for the 2014 edition verify_filter_class grades the effective bandwidth of 5.12 and the summation of 5.16 as well as the Table 1 mask, so a bank’s class is the strictest it meets on all three. Its Table 1 margins and a verdict for edition="1995" are the numbers they were.

The decimated filter banks are the other: each band now keeps its processing Nyquist frequency sixteen times its upper edge, so a band level moves by up to 0.07 dB on white noise, as the same section says.

What each .plot() draws is untouched, and so is what each .report() prints but one label: the microphone fiche writes dB(468) where it wrote dB(CCIR). 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 formula is untouched too. 4.0 rearranged the furniture and put the unit on the label; apart from those two, it did not recompute anything.