Actualizar de la 3.3 a la 4.0

La 4.0 rompe duro y no lleva capa de compatibilidad. Casi nada se ha borrado: de los 885 nombres que la raíz exportaba en la 3.3.0, diez no existen ya en ningún sitio y el resto simplemente vive en una dirección con nombre en vez de en una plana. Así que el trabajo es sobre todo un barrido de imports, y esta página es sobre todo un mapa.

Con las dos primeras secciones arreglas los imports. La tercera léela aunque tengas prisa, porque en tres sitios el arreglo evidente es el equivocado, y uno de esos tres cambia un número sin levantar nada.

En la 3.3.0 la raíz reexportaba la biblioteca entera, así que from phonometry import laeq funcionaba para casi cualquier nombre. Hoy la raíz exporta veinticinco cosas: los veintiún subpaquetes, las tres clases que no pertenecen a ningún dominio concreto (Signal, ReportMetadata, PhonometryWarning) y __version__.

import phonometry

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

from phonometry.signals import laeq     # esta es la grafía nueva

Medido sobre la superficie entera, 872 de aquellos 885 nombres de la raíz los publica hoy exactamente un subpaquete, ninguno dos, y ninguno necesita una ruta más profunda que phonometry.<subpaquete>. Otros tres siguen en la raíz, donde siempre estuvieron. Así que el cambio no tiene ambigüedad: busca el subpaquete e importa de él.

La forma de atributo no se retiró nunca, que es el cambio más pequeño posible para el código que tiraba de la raíz:

from phonometry import filters

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

En vez de buscar cada uno en la referencia, pregúntaselo al paquete instalado:

import importlib
import pkgutil

import phonometry


def whereis(name):
    """Cada módulo público que publica `name`, del menos profundo al que más."""
    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

Recorre el árbol en unos dos segundos. Cuando devuelve varias rutas, la menos profunda es el import canónico: un subpaquete reexporta lo que publican sus propios módulos, y esa ruta corta es la que usan las guías y los tests. Los cuatro nombres que la raíz sigue publicando por su cuenta, Signal, PhonometryWarning, ReportMetadata y __version__, vuelven como phonometry a secas. Una lista vacía significa que el nombre está en la última sección de esta página.

Cinco de los treinta módulos que cambiaron de ruta no se mudaron a una dirección nueva. Se dividieron, y quien siga sólo la primera mitad de la partición se lleva un ImportError por el resto. Merece la pena revisarlos uno a uno, y el paquete privado de renderizado va con ellos porque le pasó lo mismo:

Los otros veinticinco se mudaron enteros, y el resolutor de arriba los encuentra sin leer esta tabla. Cada uno de los tres primeros era alcanzable por dos rutas en la 3.3.0, la plana y la de dentro de su paquete, y las dos han desaparecido.

Todo lo demás de esta página se anuncia en cuanto lo ejecutas, y el arreglo es el que parece. Estos tres no son así.

air_density_iso y speed_of_sound_iso documentaban y consumían su temperatura en kelvin. Sus sucesores toman grados Celsius, como el resto de la biblioteca. El nombre cambió, así que el import falla y te enteras, pero el problema es el argumento que arrastras: 293,15 es un número de aspecto legítimo en cualquiera de las dos unidades.

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 frente a 477,13 m/s: un 39 % de error, sin excepción ninguna, y cada coeficiente de absorción calculado a partir de ahí sale mal en una cantidad de aspecto plausible. Convierte el valor, no te limites a renombrar la palabra clave.

Con la conversión aplicada, los dos devuelven exactamente lo que devolvían en la 3.3.0, bit a bit.

El auxiliar de ISO 17497-1 que se llamaba igual tomaba grados Celsius, así que ahí no hay conversión que hacer. La trampa es el sustituto. fluids.air() usa un modelo del medio más completo que aquella fórmula de una línea de la ISO 17497-1, y a 20 °C responde 343,99 m/s donde el auxiliar viejo respondía 343,20 m/s. Es poco, y no es nada despreciable si estás reproduciendo una medición hecha con el número antiguo. El apartado 8 de la ISO 17497-1 imprime la fórmula si necesitas ese apartado exacto.

transmission_loss pasó a propagation_loss, cosa que el import detecta, y con él se renombró el campo de dentro del resultado. Ese no levanta nada: un PropagationLossResult no tiene .tl, así que el AttributeError aparece allí donde lo leas, que puede quedar lejos de la llamada.

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, el número que guardaba .tl

El mismo renombrado llega a underwater.sonar_equation, cuyo parámetro transmission_loss es ahora propagation_loss.

Cinco puntos de entrada ya no toman las condiciones ambientales como números sueltos. Ahí no basta con renombrar la palabra clave, porque el parámetro ha desaparecido del todo:

Las sustituciones punto a punto del rotorcraft fueron por el mismo camino: bank_angle y path_angle son ahora 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)

En todo lo demás, las condiciones ambientales conservaron su sitio y ganaron un sufijo. La regla es que un parámetro público que nombra una magnitud dimensional termina en la unidad que teclea quien llama, porque el número es donde se pierde la unidad y ninguna guardia puede cazarlo por magnitud: 101,325 y 101325 son las dos presiones legítimas en esta biblioteca.

Un caso merece mención propia porque era una trampa y no una incomodidad. critical_angle era un campo en radianes en un resultado y un parámetro en grados en las dos funciones que estaban una pantalla más abajo, o sea la misma palabra para dos cosas separadas por un factor 57. Ahora es critical_angle_rad en el resultado y critical_angle_deg en los parámetros.

transmission_loss= pasó a propagation_loss= sólo en los resultados de sónar y de propagación numérica submarina. ReactiveSilencerResult y SoundReductionResult siguen llamando al suyo transmission_loss=, y con razón: es como lo llaman las normas que hay detrás.

Las funciones de la EN 29052-1 de materials siguen la misma regla, con la unidad de cada magnitud al final de su nombre:

La resistividad al flujo es la que se gana la palabra clave. La EN 29052-1 pone sus umbrales en kPa·s/m², y todas las demás resistividades al flujo de la biblioteca van en Pa·s/m², una unidad mil veces menor, así que una cifra en Pa·s/m² pasada por posición caía sin aviso en la rama equivocada del apartado 8.2; ahora se escribe por su nombre. Y por debajo de 100 kPa·s/m², installed_dynamic_stiffness ya no toma como cero un término de gas ausente: la 3.3.0 devolvía $s_{\mathrm{t}}^{\prime }$ con installed_dynamic_stiffness(20e6, 50.0), la Fórmula 6 sin su segundo término, y la 4.0 lanza un error y pide $s_{\mathrm{a}}^{\prime }$.

Dos reglas dejaron 37 firmas keyword-only. Una condición o una opción que lleva valor por defecto se escribe por su nombre, y toda bandera booleana pública es keyword-only. Las dos existen porque el sitio donde se pierde el significado es la llamada: air_attenuation(freqs, 20.0, 50.0, 101.325) son una temperatura, una humedad y una presión en un orden que no recuerda nadie, y bank.filter(x, True) no dice cuál de cinco banderas se ha activado.

El fallo es ruidoso, que es de lo que se trata:

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

Esa llamada merece una segunda mirada. leq nunca tuvo fs, porque una media energética no lo necesita, así que en la 3.3.0 el 48000 se ligaba en silencio a calibration_factor y la respuesta salía 93,6 dB alta sin una queja. Ahora es un TypeError, que es lo que siempre debió ser.

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

Los nombres públicos se habían ido repartiendo entre varias grafías de la misma magnitud, y la 4.0 se queda con la que ya usaba la mayoría. La regla de las magnitudes que se cuentan en plural es la que seguía casi toda la API: un campo o un parámetro que guarda un array es frequencies, times, distances o levels, y uno que guarda un solo valor va en singular. Un argumento vectorizado que admite un número o un array conserva su nombre.

times, levels = decay_curve(ir, fs) sigue desempaquetando la curva de caída, en el mismo orden. Los solvers FDTD conservan c y rho, que nombran los mapas en los que están escritas sus ecuaciones.

El .plot() de cada resultado se lee ahora plot(ax=None, *, ...): primero los ejes, y todo lo demás por su nombre, language incluido. Tres no empezaban por los ejes en la 3.3.0, así que plot(ax) les entregaba los ejes al parámetro equivocado:

Seis resultados posteriores a la 3.3.0 tomaban language por posición en la 4.0.0rc1: las cuatro valoraciones de protectores auditivos y los dos resultados de intensimetría en baja frecuencia. plot(ax, "es") sobre ellos es ahora plot(ax, language="es"), como en todos los demás.

Las cinco funciones verify_* devolvían dict[str, Any] y ahora devuelven una dataclase congelada, como cualquier otro resultado de la biblioteca. Dos envoltorios públicos que existían sólo para empaquetar ese diccionario se fueron con el cambio, ya que el verificador devuelve ahora el objeto él mismo.

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 es posterior a la 3.3.0, y en la 4.0.0rc1 devolvía un bool desnudo, que tiraba el intervalo impreso y el tiempo medido que había juzgado. Ahora devuelve un RunningRmsDecayVerification que conserva los dos: el veredicto es .passes, junto a .measured_time_s, .printed_time_s, .tolerance_s y el intervalo como .lower_time_s y .upper_time_s. El objeto se niega a leerse como valor de verdad, así que un if verify_running_rms_decay(...): escrito contra la versión candidata levanta TypeError en vez de dar por buenos todos los vibrómetros.

octave_filter() y OctaveFilterBank.filter() devolvían dos elementos normalmente y tres cuando sigbands=True pedía las señales por banda. La longitud de la respuesta dependía de una palabra clave, que es la razón por la que ese par necesitaba doce declaraciones @overload para poder tiparse, y por la que _, _, bands = bank.filter(...) era una línea en la que había que contar comas.

Ahora devuelven un OctaveFilterResult con campos con nombre, como cualquier otro cálculo de la biblioteca.

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 es None salvo que la llamada haya pedido sigbands=True, y levels es None en una llamada hecha con calculate_level=False. El código que necesita cualquiera de los dos puede decirlo con require_bands() o require_levels(), que devuelven el valor o fallan nombrando el argumento que faltaba, en vez de entregar un None que revienta unas líneas más adelante.

El resultado también se dibuja solo, así que el espectro de bandas es una llamada:

ax = result.plot()

Una transformación a la que se le entrega un Signal devuelve un Signal desde que se escribió el contrato, pero cinco objetos de resultado todavía guardaban su forma de onda como un array desnudo junto a un fs suelto. Ahora conservan el tipo con el que llegó la entrada:

Un array desnudo sigue devolviendo un array desnudo, así que el código que pasa arrays no lo nota. El código que pasa un Signal y hace aritmética con uno de estos campos pasa por np.asarray, como con cualquier Signal, y una entrada calibrada vuelve con calibration_factor=1.0, así que el campo alimenta a la función siguiente en pascales sin que el factor se aplique otra vez.

io.read_blocks es posterior a la 3.3.0, y en la 4.0.0rc1 entregaba arrays float64 desnudos. Ahora entrega un Signal por bloque, con la frecuencia de muestreo, la calibración, las etiquetas de canal y la procedencia que da io.read, y toma el mismo calibration_factor= y lee el mismo sidecar. Para un bucle escrito contra la versión candidata cambian dos cosas. Un bloque de un archivo calibrado llega a los filtros y a las funciones de nivel en pascales, así que un calibration_factor aplicado a mano encima cuenta dos veces. Y la aritmética sobre un bloque, o sobre lo que un filtro devuelve para él, pasa por np.asarray, como con cualquier Signal.

Toda tabla que la biblioteca publica a nivel de módulo es de sólo lectura en la 4.0. En la 3.3.0 las tablas publicadas eran diccionarios corrientes y los arrays publicados admitían aritmética sobre el propio array, así que una línea como REFERENCE_CURVE[500] = 0.9 o BAND_IMPORTANCE *= 2 cambiaba el número para todo lo que se ejecutara después en el mismo proceso, sin que nada lo avisara. Los diccionarios son ahora types.MappingProxyType, también los que van anidados dentro de otra tabla, y los arrays tienen desactivada la bandera writeable. Leer no cambia; escribir lanza TypeError en una tabla y ValueError en un array.

El código que retocaba una tabla publicada tiene que copiarla antes:

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

Una tabla que lleva tablas dentro necesita copiar cada nivel, como en {area: dict(rows) for area, rows in GUIDE_VALUES.items()}. La misma copia hace falta antes de serializar una tabla con pickle, copiarla en profundidad o escribirla como JSON, porque un mapeo de sólo lectura no admite ninguna de las tres cosas.

Los catálogos publicados de materiales son nuevos en la 4.0: ni la 3.3.0 ni la 4.0.0rc1 los tenían. Cambiaron de forma una vez de camino a la versión final, y el código escrito contra la rama principal entretanto necesita los cambios de abajo. Todas las filas de todos los catálogos comparten ahora una base, io.CatalogueRow (con io.BandedRow para una fila que imprime un valor por banda), y las mismas tres preguntas tienen la misma respuesta en cualquiera de ellas.

is_derived responde ahora sólo por lo que calcula la biblioteca y podría volver a calcular con las celdas de la propia fila, como una velocidad de barra obtenida de un módulo y una densidad. Un valor que la página da en otra unidad sigue siendo el número de la página, y también lo es uno que da por referencia a otra de sus filas, así que ninguno de los dos es ya derivado. basis_of responde con la entrada del propio campo, si no con la de la fila, y si no con una cadena vacía, que quiere decir que la fuente no dice cómo se obtuvo el número; las cinco cosas que puede afirmar una fuente están en 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

Las capas elásticas pasaron a ser filas de catálogo en el mismo cambio. Una ResilientLayer es una io.CatalogueRow como cualquier otra fila, con la clave y la atribución de las demás:

La Tabla A3 de Hopkins imprime $s^{\prime }$, la rigidez de la capa instalada tal como la define la lista de símbolos del propio libro, así que sus quince filas siguen guardando dynamic_stiffness_n_m3 y devuelven las frecuencias naturales que devolvían. Cuatro de ellas guardan una densidad que la página imprime una sola vez para su bloque y deja en blanco en su propia línea, y layer.carried["density_kg_m3"] nombra ahora la fila que la imprime; la densidad es la misma.

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

Toda fila de catálogo se comprueba en su constructor, la construya la biblioteca a partir de una tabla empaquetada o quien llama a mano, y una celda que nada de lo que viene después podría leer lanza io.CatalogueError, nombrando la fila y el campo. El código escrito entretanto contra la rama principal que contara con que se aceptara algo de lo siguiente tiene que cambiar:

Todas las demás filas empaquetadas cumplían ya el contrato, así que esas seis porosidades son las únicas celdas publicadas que cambian, y todas las filas porosas publicadas con los dos módulos imprimen su factor de pérdidas.

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 calificaba solo la máscara de la Tabla 1. Para la edición de 2014 califica ahora también la desviación del ancho de banda efectivo del 5.12 y la suma de las señales de salida del 5.16, calculadas como las calcula IEC 61260-2:2016, y la class de una banda y la overall_class del banco son la clase más estricta que se cumple en los tres. Un veredicto con edition="1995" no cambia.

Los bancos de octavas y de tercios de octava siguen siendo clase 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

Todo lo demás se movió. Estos diez no existen en ningún módulo público:

Los números. El informe de conformidad son las mismas 995 comprobaciones contra las mismas normas con los mismos valores esperados que tenía antes de la reorganización, y de cada renombrado de esta página se comprobó que devuelve lo que devolvía su predecesor. Si un resultado se mueve después de que termines de actualizar, eso es un defecto y merece la pena avisar.

Un veredicto es la excepción, y la sección sobre las clases de filtro de más arriba explica cómo: para la edición de 2014, verify_filter_class califica el ancho de banda efectivo del 5.12 y la suma de salidas del 5.16 además de la máscara de la Tabla 1, así que la clase de un banco es la más estricta que cumple en los tres. Sus márgenes de la Tabla 1 y un veredicto con edition="1995" son los números que eran.

Los bancos de filtros diezmados son la otra: cada banda conserva ahora su frecuencia de Nyquist de proceso en dieciséis veces su borde superior, así que el nivel de una banda se mueve hasta 0,07 dB con ruido blanco, como dice la misma sección.

Lo que dibuja cada .plot() está intacto, y también lo que imprime cada .report() salvo una etiqueta: la ficha del micrófono escribe dB(468) donde escribía dB(CCIR). El contrato de Signal es el que era, ahora cumplido en dos sitios más, los bloques de read_blocks y las formas de onda dentro de cinco resultados. Cada fórmula está intacta también. La 4.0 recolocó los muebles y puso la unidad en la etiqueta; salvo esas dos, no recalculó nada.