materials.absorbers.measured

Absorption coefficients as the books print them, one row per finish.

The other catalogues of this package hold what a material is: a flow resistivity, a porosity, a modulus. This one holds what a surface did in a reverberation room, band by band, which is a different kind of number. It is not a property of the material but of a specimen, a mounting and a room, and the books say so in their own ways: Bies calls his “Sabine absorption coefficients for some commonly used materials”, which names the method and hedges the sample in one line. So a row here is a measurement somebody once made, kept because it is what the room-acoustics formulas of this library ask for and because no reader has a reverberation room to hand.

A table of absorption coefficients usually carries a few rows that are not coefficients at all. Bies prints an audience “per person seated” as $S\bar{\alpha }$ in square metres, an absorption area, in the same columns as the coefficients above it, and Long prints a musician with instrument the same way, in figures that are sabins. A coefficient is dimensionless and bounded by the surface it belongs to; an area per person is a quantity in square metres that is added, not multiplied. Holding both under one field name would put a number in square metres behind a name that says otherwise, so they are two classes and two catalogues, PUBLISHED_ABSORPTION and PUBLISHED_ABSORPTION_AREAS, and the data file tells them apart by the fields each row carries.

Each octave band is a field of its own, absorption_coefficient_125 and so on, with the band’s centre frequency in hertz as the suffix. That is not the tidiest shape for a spectrum and it is the right one for a catalogue: every hedge of CatalogueRow is keyed by field name, so a cell the page prints as a range, or leaves empty, or prints wrong, is handled the way the same cell is handled in every other catalogue, and why_missing answers for a band the way it answers for a modulus. AbsorptionSpectrum.bands and AbsorptionSpectrum.spectrum give the row back as a spectrum for the caller who wants one.

A reverberation-room coefficient depends on the sample size, the mounting and the room, which is why ISO 354 fixes all three and why a coefficient above 1 is common and not an error. Bies prints no mounting; Long prints the ASTM C423 mounting on most rows and the same fibreglass board twice, on the test-room floor and over a 400 mm airspace, with a different spectrum each time, and AbsorptionSpectrum.mounting keeps that apart. The books that print a thickness print it in the name. A row is therefore a representative value for a finish of that description on that mount, useful for a reverberation estimate and for a sanity check on a measurement, and not a specification of any product. Where a page says more than that about its numbers, the about of its data file quotes it.

Long sets his table in inches, pounds and ounces, and his two rows that are areas are in sabins, square feet of perfect absorption: the air names its sabins, and the musician prints bare figures that are read in the same unit, as its note explains. The names keep the inches, because a name is what the page prints; the areas are converted to square metres at load, because a field named m2 holds square metres or it lies, and each converted cell keeps the page’s figure and its unit.

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

Constant (tuple).

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

absorption_named(name: str) -> tuple[AbsorptionSpectrum, ...]

Every published coefficient row whose name contains name.

A finish is described rather than named, and no two books describe one the same way, so this matches a fragment inside the printed name, without regard to case: "carpet" answers with every carpet of every table, and the caller reads the names to pick the one that is the carpet they mean. That is deliberate. A lookup that returned one row for “carpet” would be choosing a thickness, a backing and a floor on the caller’s behalf.

Parameters

Returns: The rows whose AbsorptionSpectrum.name contains it, in the order the tables are read, which is empty when no page has one.

AbsorptionAreaSpectrum(
    *,
    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 = '',
    absorption_area_63_m2: float | None = None,
    absorption_area_125_m2: float | None = None,
    absorption_area_250_m2: float | None = None,
    absorption_area_500_m2: float | None = None,
    absorption_area_1000_m2: float | None = None,
    absorption_area_2000_m2: float | None = None,
    absorption_area_4000_m2: float | None = None,
    absorption_area_8000_m2: float | None = None,
    per: str = 'person',
)

One row a table prints as an absorption area rather than a coefficient.

An audience, a chair, a person standing: things a book prices per unit in square metres of equivalent absorption, because they have no surface area a coefficient could multiply. The fields carry the unit in their name so that a number from here cannot be mistaken for a coefficient.

Attributes

A table set in feet prints its areas in sabins, and from_printed takes them under the band’s field name with _ft2 in place of _m2, or _ft2_per_1000_ft3 for sabins per thousand cubic feet, which then needs per written beside it, because its default is a person. The page’s figure is converted on its digits with the exact factor of the 1959 foot and rounded once, and converted keeps the figure and its unit, so the page’s own number is never more than a lookup away. It is not a derivation: the value is the page’s, in another unit.

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

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

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

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

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

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

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

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

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

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

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

AbsorptionSpectrum(
    *,
    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 = '',
    absorption_coefficient_63: float | None = None,
    absorption_coefficient_125: float | None = None,
    absorption_coefficient_250: float | None = None,
    absorption_coefficient_500: float | None = None,
    absorption_coefficient_1000: float | None = None,
    absorption_coefficient_2000: float | None = None,
    absorption_coefficient_4000: float | None = None,
    absorption_coefficient_8000: float | None = None,
    mounting: str = '',
)

One finish of a published table, with its coefficient in each band.

The hedges of CatalogueRow apply to each band as to any other field, and the material’s thickness, density or mounting are part of name, as the page prints them, because the books print them there and pulling them into fields would mean deciding what “heavy carpet on concrete” is a thickness of.

Attributes

AbsorptionSpectrum.absorption_coefficient(band_hz: int) -> float

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

Parameters

Returns: The printed coefficient, as a float.

Raises

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

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

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

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

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

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

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

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

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

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

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

Constant (mapping).

Constant (mapping).