materials.absorbers.datasheets

Sound absorption as a data sheet or a test report prints it.

The absorption tables of the books (measured) print one Sabine coefficient per octave and rarely say how it was measured. A product’s data sheet, its declaration of performance and the laboratory’s test report print something narrower and better defined, and they print it in two shapes that are not the same quantity:

• the sound absorption coefficient ${\alpha }_{\mathrm{s}}$ of ISO 354, one value per one-third octave band as the reverberation room measured it, which can exceed 1 (ISO 354 3.9, NOTE 2, gives diffraction effects as the reason) and carries every digit the laboratory reported; and
• the practical sound absorption coefficient ${\alpha }_{\mathrm{p}}$ of ISO 11654 Clause 4.1, one value per octave band from 125 Hz to 4 kHz, the mean of the three one-third octaves in it rounded in steps of 0,05 and capped at 1,00.

The two are two classes here, ThirdOctaveAbsorptionSpectrum and PracticalAbsorptionSpectrum, because the band resolution and the rounding are part of what the number is, and a row that held either under one name would let an ${\alpha }_{\mathrm{p}}$ pass for a measurement it was averaged and rounded from. The quantity lives in the class, never in a flag, and a catalogue file says which one it holds by its row_type.

Both carry the single-number rating the sheet prints beside the bands, the weighted sound absorption coefficient ${\alpha }_{\mathrm{w}}$ of ISO 11654 Clause 4.2 with its shape indicators and its class, and both work it out again from the bands with PracticalAbsorptionSpectrum.rating or ThirdOctaveAbsorptionSpectrum.rating. The printed rating is kept as printed; the one worked out is the library’s, and when a catalogue file is read the two are compared and any difference is noted beside the catalogue, never reconciled.

The 125 Hz octave of ${\alpha }_{\mathrm{p}}$ is defined like the others (ISO 11654 Clause 4.1 forms ${\alpha }_{\mathrm{p}}$ for each octave band, and Clause 5.2 plots it from 125 Hz) and is not rated: the reference curve starts at 250 Hz, and Clause 1 says the rating is not appropriate below it. So a row holds it and PracticalAbsorptionSpectrum.rating never reads it.

Nothing here ships with data. A caller’s own catalogue holds these rows, read by phonometry.io.read_catalogue from the file the caller typed from the sheet.

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

PracticalAbsorptionSpectrum(
    *,
    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 = '',
    provenance: Provenance | None = None,
    weighted_absorption_coefficient: float | None = None,
    shape_indicator: str = '',
    absorption_class: str = '',
    noise_reduction_coefficient: float | None = None,
    mounting: str = '',
    thickness_mm: float | None = None,
    construction_depth_mm: float | None = None,
    practical_absorption_coefficient_125: float | None = None,
    practical_absorption_coefficient_250: float | None = None,
    practical_absorption_coefficient_500: float | None = None,
    practical_absorption_coefficient_1000: float | None = None,
    practical_absorption_coefficient_2000: float | None = None,
    practical_absorption_coefficient_4000: float | None = None,
)

One specimen of a data sheet, with its practical coefficient per octave.

The practical sound absorption coefficient ${\alpha }_{\mathrm{p}}$ of ISO 11654 Clause 4.1 is the mean of the three one-third-octave coefficients of ISO 354 inside an octave, worked out to the second decimal, rounded in steps of 0,05 and set to 1,00 when it rounds above. Six values from 125 Hz to 4 kHz all ending in 0 or 5 look like these, though only a sheet that names them says so. A row of this class holds them as printed, a value above 1,00 or off the steps included: the reader of a catalogue file notes such a value, and nothing here corrects it.

A declaration under a product standard declares the coefficients as a level no result falls below (EN 13162 Clause 4.3.11 does, for mineral wool), so a sheet that says it declares them is recorded with basis "declared".

Attributes

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

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

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

PracticalAbsorptionSpectrum.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 in another unit of the same kind as its field (thickness_m for thickness_mm, flow_resistivity_kpa_s_m2 for flow_resistivity_pa_s_m2), or in 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, whether it is a value or stands as the key of a hedge (the ends of a range, the readings of a list and a plus-or-minus convert with it), and converted records the figure and its unit. Every number of one cell is written in one 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

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

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

PracticalAbsorptionSpectrum.practical_absorption_coefficient(
    band_hz: int,
) -> float

The practical coefficient in one octave, or a refusal.

Parameters

Returns: The printed ${\alpha }_{\mathrm{p}}$, as a float.

Raises

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

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

PracticalAbsorptionSpectrum.rating() -> AbsorptionRatingResult

The weighted sound absorption coefficient of the row’s octaves.

weighted_absorption on the five rating bands, 250 Hz to 4 kHz (ISO 11654 Clause 4.2), which snaps each value to the 0,05 grid and caps it at 1,00 as Clause 4.1 would have. The 125 Hz band is not read. The rating the sheet prints beside the bands is not consulted either: this is the one the bands give, and phonometry.io.read_catalogue notes when the two differ.

Returns: The AbsorptionRatingResult, with ${\alpha }_{\mathrm{w}}$, the shape indicators and the class.

Raises

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

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

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

The sentence names the document by its kind: "the datasheet", "the test report", and "the page" for a row with no provenance, which is every packaged one. For a cell the row holds in another unit than the page’s, a bound, a range or a list quotes the page’s figure and unit first and the row’s value after it: "the datasheet prints a lower bound of 5 kPa s/m2 (5000 Pa s/m2) and no value", never a figure the page does not print.

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

ThirdOctaveAbsorptionSpectrum(
    *,
    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 = '',
    provenance: Provenance | None = None,
    weighted_absorption_coefficient: float | None = None,
    shape_indicator: str = '',
    absorption_class: str = '',
    noise_reduction_coefficient: float | None = None,
    mounting: str = '',
    thickness_mm: float | None = None,
    construction_depth_mm: float | None = None,
    absorption_coefficient_50: float | None = None,
    absorption_coefficient_63: float | None = None,
    absorption_coefficient_80: float | None = None,
    absorption_coefficient_100: float | None = None,
    absorption_coefficient_125: float | None = None,
    absorption_coefficient_160: float | None = None,
    absorption_coefficient_200: float | None = None,
    absorption_coefficient_250: float | None = None,
    absorption_coefficient_315: float | None = None,
    absorption_coefficient_400: float | None = None,
    absorption_coefficient_500: float | None = None,
    absorption_coefficient_630: float | None = None,
    absorption_coefficient_800: float | None = None,
    absorption_coefficient_1000: float | None = None,
    absorption_coefficient_1250: float | None = None,
    absorption_coefficient_1600: float | None = None,
    absorption_coefficient_2000: float | None = None,
    absorption_coefficient_2500: float | None = None,
    absorption_coefficient_3150: float | None = None,
    absorption_coefficient_4000: float | None = None,
    absorption_coefficient_5000: float | None = None,
    absorption_coefficient_6300: float | None = None,
    absorption_coefficient_8000: float | None = None,
    absorption_coefficient_10000: float | None = None,
)

One specimen of a test report, with its coefficient per one-third octave.

The sound absorption coefficient ${\alpha }_{\mathrm{s}}$ of ISO 354, as the reverberation room measured it: one value per one-third octave band, 100 Hz to 5 kHz in the standard’s range and from 50 Hz to 10 kHz where a laboratory reports more. A value above 1 is common and not an error: ISO 354 (3.9, NOTE 2) says a coefficient evaluated from reverberation times can exceed 1,0, for example because of diffraction effects. Nothing here caps it.

practical turns the row into its practical coefficients, and rating rates it; both leave out an octave the row cannot give all three of its one-third octaves for. A negative coefficient, which a measurement can give in a band where the specimen adds almost nothing to the room’s absorption, is never read as 0 nor left out of a mean: the octave it falls in gets no practical coefficient, and rating refuses it.

Attributes

ThirdOctaveAbsorptionSpectrum.absorption_coefficient(band_hz: int) -> float

The coefficient in one one-third octave band, or a refusal.

Parameters

Returns: The printed ${\alpha }_{\mathrm{s}}$, as a float.

Raises

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

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

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

ThirdOctaveAbsorptionSpectrum.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 in another unit of the same kind as its field (thickness_m for thickness_mm, flow_resistivity_kpa_s_m2 for flow_resistivity_pa_s_m2), or in 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, whether it is a value or stands as the key of a hedge (the ends of a range, the readings of a list and a plus-or-minus convert with it), and converted records the figure and its unit. Every number of one cell is written in one 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

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

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

ThirdOctaveAbsorptionSpectrum.practical() -> PracticalAbsorptionSpectrum

The row’s practical coefficients, octave by octave (ISO 11654 4.1).

Each octave from 125 Hz to 4 kHz whose three one-third octaves the row prints is the mean of the three, worked out to the second decimal and rounded in steps of 0,05, capped at 1,00, and marked in derived with the bands it comes from; when those bands do not share one basis, the text names the basis of each. An octave with a one-third octave the row does not print as a number stays empty, and its why_missing says it does not follow from the cells the row has: nothing is borrowed from a neighbouring band. An octave with a negative one-third-octave coefficient stays empty too, with the band and the value in its not_derivable: a negative value is neither read as 0 nor left out of the mean, so PracticalAbsorptionSpectrum.rating of the result refuses a rating band this empties, as rating refuses the band itself.

The name, the source, the provenance and what the report prints about the specimen (the mounting, the thickness, the depth of construction and the printed rating, with every hedge on them) pass to the practical row unchanged.

Returns: A new PracticalAbsorptionSpectrum.

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

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

ThirdOctaveAbsorptionSpectrum.rating() -> AbsorptionRatingResult

The weighted sound absorption coefficient of the row’s bands.

weighted_absorption_from_third_octave on the fifteen one-third octaves from 200 Hz to 5 kHz: the practical coefficients of the five rating octaves (ISO 11654 Clause 4.1), then the reference curve shifted over them (Clause 4.2). The result keeps the fifteen values it was formed from. The rating the report prints is not consulted: phonometry.io.read_catalogue notes when it differs from this one.

Returns: The AbsorptionRatingResult.

Raises

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

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

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

The sentence names the document by its kind: "the datasheet", "the test report", and "the page" for a row with no provenance, which is every packaged one. For a cell the row holds in another unit than the page’s, a bound, a range or a list quotes the page’s figure and unit first and the row’s value after it: "the datasheet prints a lower bound of 5 kPa s/m2 (5000 Pa s/m2) and no value", never a figure the page does not print.

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