building.catalogue

Transmission loss as the books print it, one row per construction.

A partition’s transmission loss is not a property of a material. It is what one wall, built one way and mounted one way, did in one laboratory, and the number changes with the studs, the ties, the sealing of the joints and the size of the specimen. The models of phonometry.building.prediction compute it from mass, stiffness and geometry; this module holds what was measured, so that a prediction has something published to sit beside.

The mass law gives a straight line. A real partition departs from it at the critical frequency, at the mass-air-mass resonance of a double leaf and wherever a stud shorts the two leaves together, and the size of those departures is what a table like this shows and no formula in the book reproduces. Two rows of the same brick wall, same mass and same thickness, differ by 15 dB at 500 Hz and by 9 at 4 kHz because one is tied with strips and the other with expanded metal, which is the whole argument for resilient connections and is in the table rather than in the theory.

Each octave band is a field of its own, transmission_loss_500_db and so on, with the band’s centre frequency in hertz and the unit in the name. Every hedge of CatalogueRow works on a band the way it works on any other field, so a band the page leaves empty says so through why_missing rather than answering zero. The thickness and the surface density the page prints beside the description are fields of their own, because they are what a reader compares two constructions by, and because the mass law needs the second one.

Bies calls his values “representative” and says only that they come from tests published “by manufacturers and testing laboratories”, without naming a measurement standard, a mounting or a source for any row; that sentence is quoted in full in the about of the data file. The qualifier the book does give is “field incidence”, which is the transmission loss of a diffuse field over the range of angles a laboratory measures, and is what its own theory computes. So a row here is a published measurement of a construction of that description, useful for a sanity check and for an order of magnitude, and it is not a specification of any wall anybody will build.

ASHRAE says as little and says it plainly: its nine machine equipment room constructions are “compiled from controlled laboratory tests and represent a condition typically superior to that found in field installations, because the in situ acoustical performance of any wall, floor, or ceiling is adversely affected by flanking paths, holes, penetrations, and other anomalies”. No laboratory, standard or reference is named for any of them either. Those rows are here and the duct walls of the same chapter are not, because a duct wall is measured in two directions that are different numbers and is indexed by the duct’s cross section, length and sheet gauge; it is published from phonometry.noise_control.duct_walls.

Rossing’s Table 11.4 is the same kind of row with fewer bands: twenty-three common partitions, six octaves from 125 Hz to 4 kHz and a sound transmission class, with no source, laboratory or standard named for any of them.

Chapter 31 of the Spanish edition of Harris prints seven tables of sound transmission class alone, with no frequency band anywhere: stud walls in six conditions, concrete block walls of two weights, block walls under six plasterboard mountings, doors unsealed and sealed, exterior doors, sealed windows and floor-ceiling systems. Each is a row of this catalogue with every band empty, and the rating in TransmissionLossSpectrum.sound_transmission_class. A caller after a spectrum reads the band fields and finds None; TransmissionLossSpectrum.transmission_loss_db then refuses with the row and the band, because the page printed nothing there.

Most of those tables print one construction under several conditions, as columns: the plasterboard layers and the cavity absorbent of Table 31.2, the sealing of the doors of Table 31.6. A column is a row here, the construction is its name and the column its variant, composed from the printed headings above the cell. The window table is printed the other way round, with the ratings as rows and the glazings as cells, and is turned so that a row is a window. A row the page leaves blank is a configuration it does not rate and has no row.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

Constant (mapping).

Constant (tuple).

TRANSMISSION_LOSS_BANDS_HZ = (63, 125, 250, 500, 1000, 2000, 4000, 8000)

transmission_loss_named(name: str) -> tuple[TransmissionLossSpectrum, ...]

Every published row whose printed description contains name.

Parameters

Returns: The rows whose description contains it, in the order the tables are read, which is empty when no page has one. It matches the printed description and nothing else, in the language the page is set in: "door" answers with the rows that carry the word, and not with Bies’s hollow flush panel or solid hardwood, which the page describes without it, nor with the doors of the Spanish edition of Harris, which are "puerta". The caller reads the thickness, the surface density and the variant to pick the row they mean.

TransmissionLossSpectrum(
    *,
    name: str,
    source: str,
    table: str = '',
    variant: str = '',
    basis: Mapping[str, str] = ...,
    approximate: frozenset[str] = frozenset(),
    derived: Mapping[str, str] = ...,
    converted: Mapping[str, tuple[str, str]] = ...,
    carried: Mapping[str, str] = ...,
    ranges: Mapping[str, tuple[float | None, float | None]] = ...,
    bounded_above: frozenset[str] = frozenset(),
    bounded_below: frozenset[str] = frozenset(),
    reported: Mapping[str, tuple[float | tuple[float, float], ...]] = ...,
    unquantified: Mapping[str, str] = ...,
    uncertainty: Mapping[str, float] = ...,
    not_derivable: Mapping[str, str] = ...,
    misprinted: Mapping[str, str] = ...,
    attributed_to: Mapping[str, str] = ...,
    group: str = '',
    note: str = '',
    transmission_loss_63_db: float | None = None,
    transmission_loss_125_db: float | None = None,
    transmission_loss_250_db: float | None = None,
    transmission_loss_500_db: float | None = None,
    transmission_loss_1000_db: float | None = None,
    transmission_loss_2000_db: float | None = None,
    transmission_loss_4000_db: float | None = None,
    transmission_loss_8000_db: float | None = None,
    thickness_mm: float | None = None,
    surface_density_kg_m2: float | None = None,
    sound_transmission_class: float | None = None,
    block_mass_kg: float | None = None,
    refers_to_row: str = '',
)

One construction of a published table, with its loss in each band.

Attributes

TransmissionLossSpectrum.bands() -> tuple[int, ...]

The bands this row prints a value for, in hertz.

TransmissionLossSpectrum.basis_of(field_name: str) -> str

What the source says this field is, one of CATALOGUE_BASES.

The five are measured, declared, calculated, estimated and extended.

Parameters

Returns: The field’s own entry in basis, else the row’s, else the empty string, which means the source does not say.

classmethod

TransmissionLossSpectrum.from_printed(**cells: Any) -> Self

A row built from the cells its page prints, completed and marked.

The one path that works anything out. The cells are what the page prints, under the field names of the class and with the hedges each cell carries, as a data file writes them. A figure written under a unit the class takes as an alias of its own (an AbsorptionAreaSpectrum takes absorption_area_125_ft2 for absorption_area_125_m2) is converted on its digits with an exact factor and rounded once, and converted records the figure and its unit. The row is then built and held to the contract the class docstring lists, so every cell is checked before any arithmetic reads it. Last, the class fills what follows from those cells (a modulus from a plate speed, a density and a Poisson ratio), never over a cell that holds a value or one the row says something else about, and derived says how each filled value was reached and, when the cells it rests on do not share one basis, the basis of each. Cells the arithmetic cannot take are refused rather than turned into a value that would be wrong: a modulus of 1 GPa and a shear modulus of 0.1 GPa give a Poisson ratio of 4, which no isotropic solid has, and a row whose cells are not meant to give a value says so in not_derivable, which keeps the arithmetic from running.

Cls(...) stays literal: it holds what it is given and works nothing out. To change a cell of a row and have what follows from it follow again, change it in printed_fields and build again here; dataclasses.replace would copy the derived values as they were:

cells = row.printed_fields()
cells["density_kg_m3"] = 2400.0
row = type(row).from_printed(**cells)

Parameters

Returns: The row, with what follows from its cells filled in.

Raises

TransmissionLossSpectrum.is_approximate(field_name: str) -> bool

Whether the page prints this field with a ~.

Parameters

Returns: True when the page rounded the cell on purpose.

TransmissionLossSpectrum.is_derived(field_name: str) -> bool

Whether this library computed this field instead of reading it.

Parameters

Returns: True when the page did not print it and the value follows from cells that it did. derived says how. A value the page prints in another unit, or gives by reference to another of its rows, answers False: the number is the page’s, and converted or carried says so.

TransmissionLossSpectrum.printed(
    field_name: str,
    *,
    wanted_by: str = 'the caller',
) -> float

One quantity this page prints, or a refusal that says what it had.

Every quantity of a row is optional, because the pages print different columns, so a caller passing one into a function that requires a float has to narrow it. Doing it here beats an assertion at each call site: the refusal names the field, who wanted it and what the page had in that cell, which is the difference between a cell the book left empty and a cell holding the word “model”.

Parameters

Returns: The value, as a float.

Raises

TransmissionLossSpectrum.printed_fields() -> dict[str, Any]

The cells the page prints, as from_printed takes them.

Every field, the name, the citation, the table and every hedge included, except the values this library derived, derived itself, and a field left at a default that holds nothing (a quantity the page leaves out, an empty text or hedge). A text field whose default says something is kept even when it holds no text: the per of an area per unit is a person unless the row says otherwise, and a row that leaves it empty has said otherwise. A value converted from the page’s unit and one the page gives by reference to another of its rows are the page’s, so they stay, with converted and carried beside them.

For every row from_printed builds, and so for every packaged one, type(row).from_printed(**row.printed_fields()) is the row again, and changing a cell before building it again is how a row is edited without carrying a derived value that no longer follows from it. A derived passed to the literal constructor is the caller’s own; it is left out here with its value, like every derived one, so building again gives back only what the class works out.

Returns: A new dictionary of constructor keywords. The values are the ones the row holds, frozen as the row holds them.

TransmissionLossSpectrum.spectrum() -> dict[int, float]

The row as {band_hz: value} over the bands it prints.

A band the page left empty, or printed as something other than a number, is left out rather than filled with a zero; why_missing on that band’s field says which it was.

TransmissionLossSpectrum.transmission_loss_db(band_hz: int) -> float

The loss in one band, or a refusal that says what the page had.

Parameters

Returns: The printed transmission loss, in decibels.

Raises

TransmissionLossSpectrum.values_at(
    frequencies_hz: ArrayLike,
) -> NDArray[np.float64]

The row’s value at each of frequencies_hz, or a refusal.

The adapter for a function that takes one value per band by position (the absorption of a surface in a reverberation formula, the transmission loss of a panel at the frequencies an enclosure model asks for), because an array handed over by position cannot say which band is missing and a row can. Each frequency is read as the band of these tables whose centre is nearest on a logarithmic scale, and matches it when it lies within a sixth of the spacing between bands: a sixth of an octave for octave bands, an eighteenth for one-third octave bands. That takes the nominal centre, the exact base-ten one and the exact base-two one alike (160 Hz, 158.49 Hz and 157.49 Hz are one band) and never reaches the next band. A band the row does not print is refused, as printed refuses it, with what the page had there; it is never read as zero and never filled from its neighbours.

Parameters

Returns: A new array of the same shape, one value per frequency.

Raises

TransmissionLossSpectrum.why_missing(field_name: str) -> str

Why this field is None, in the page’s own terms.

A catalogue that answers None and stops is asking the caller to guess whether the material has no such property, whether the book measured it and printed a dash, or whether the cell holds something that is not a number. Each of those is a different answer.

Parameters

Returns: What the page had in that cell, or the empty string when the field is not missing at all. A field the page has no column for and this library cannot derive, because the cells it would need are themselves a range, answers that it does not follow.

Raises