materials.absorbers.catalogue

Porous specimens as the pages that print them have them.

The five-parameter models of porous take a flow resistivity, a porosity, a tortuosity and two characteristic lengths, and a caller who has not characterised a specimen to ISO 9053 and ISO 10534-2 has nowhere to get them. They get them here, from a book, with the page the row came off attached to it.

A parameter table is a set of numbers someone fed a model, not a set of measurements of a material, and the books say so in different ways. Allard and Atalla print thirty-odd such rows across nineteen tables, every one of them the input to a worked example, and one of the rows prints the word model in three of its cells because the quantity there is frequency dependent and no single number stands for it. A catalogue that turned that word into a float would be inventing a tortuosity nobody published, so unquantified carries the word instead and why_missing hands it back.

The same applies to the elastic constants. Table 6.1 prints a complex shear modulus, 220(1 + j0.1) N/cm2, and Table 11.8 prints the same specimen as a Young’s modulus of 4,4 MPa with a structural loss factor of 0,1; they agree, because E / (2(1 + nu)) is the real part of the first. A row therefore stores the real modulus and the loss factor separately, which is the form the poroelastic models take them in, and PorousMaterial.frame_constants puts the complex number back together.

A specimen row is one sample, with every parameter a model needs beside it: Allard and Atalla’s tables are all of this kind, and a row of one of them reproduces the worked example it belongs to. A compiled row is one quantity over a class of material, gathered by its book from the literature: Cox and D’Antonio compile a flow resistivity, a fibre diameter, a porosity, two characteristic lengths and a tortuosity, and Mechel compiles a porosity and the fibre data of three product groups. Almost every compiled cell is an interval, because there is no such thing as the porosity of mineral wool, only the range the measurements fall in, and a row that answered with the midpoint of that range would be inventing a measurement.

The two kinds sit in one catalogue because they answer one question between them: porous_materials_named asks a name of every book at once, and a specimen that falls outside the range its class is compiled in is worth knowing about. What tells them apart is what a row holds: a specimen carries several quantities, a compiled row carries one, and the compiled one carries it as a range.

In absorbers/data/*.json, one file per published table, read at import through the package-data reader in phonometry._internal. The citation is written once, in the file that holds the rows it belongs to, and the provenance gate reads it from there.

It is not a material database. Every row here is a parameter set from a worked example of a book, which is what makes it reproducible and also what makes it specific: the foam of one figure is that foam, not foam. Use a row to reproduce the example it belongs to, to sanity-check an implementation, or to get an order of magnitude; characterise a specimen for anything that has to be right.

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

porous_materials_named(name: str) -> tuple[PorousMaterial, ...]

Every published row for a specimen name, across the tables.

Comparing two printings of one specimen is the point of holding both, and it has to be a deliberate act: a lookup that returned one row for “Foam” would be choosing between published parameter sets on the caller’s behalf, and one of these books prints five different foams under that name. Across the books it also puts a measured specimen beside the range its class is compiled in: “Mineral wool” answers with Allard’s specimen and with the two ranges Cox compiles for it.

Parameters

Returns: The rows whose PorousMaterial.name matches, in the order the tables are read, which is empty when no page names it.

PorousMaterial(
    *,
    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 = '',
    flow_resistivity_pa_s_m2: float | None = None,
    porosity: float | None = None,
    tortuosity: float | None = None,
    viscous_length_um: float | None = None,
    thermal_length_um: float | None = None,
    thermal_permeability_m2: float | None = None,
    fibre_diameter_um: float | None = None,
    fibre_diameter_distribution_parameter: float | None = None,
    shot_content_percent: float | None = None,
    binder_content_percent: float | None = None,
    frame_density_kg_m3: float | None = None,
    thickness_mm: float | None = None,
    youngs_modulus_pa: float | None = None,
    shear_modulus_pa: float | None = None,
    poisson_ratio: float | None = None,
    structural_loss_factor: float | None = None,
)

One row of a published table of porous-material parameters.

Every quantity is optional, because no two tables print the same columns: a chapter on the Biot theory prints a shear modulus and no characteristic length, a chapter on the transfer matrix prints both lengths and a Young’s modulus, and the one anisotropic table prints two flow resistivities and no elastic constant the isotropic models can take. A field is None when the page had nothing to put there, and why_missing says what it had instead.

The name, the citation, the variant and the hedges a cell can carry instead of a number are the ones every catalogue row has.

Attributes

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

PorousMaterial.frame_constants() -> tuple[complex, float]

The in-vacuo frame constants (N, nu) the source prints.

The complex shear modulus and the Poisson ratio are what biot_waves, frame_quarter_wave_resonance and PoroelasticLayer take together, and a table that prints one prints the other, so they are asked for together and a specimen characterised as a rigid frame alone says so here rather than handing out a None that fails further down.

The shear modulus comes back complex, N(1 + j eta_s), which is the form the page prints and the models take, rebuilt from the real modulus and the loss factor the row stores separately. A row whose page printed a Young’s modulus instead has had its shear modulus derived through the Poisson ratio, and derived says so.

The loss factor is asked for like the other two. A row whose page prints the moduli and no loss factor is refused rather than handed a frame with eta_s = 0: a lossless frame is a claim about the material, and a cell the page left empty is not a zero. Every published row that prints both moduli prints the loss factor too.

Returns: (shear_modulus_pa, poisson_ratio), the first complex.

Raises

classmethod

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

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

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

PorousMaterial.medium(
    frequency: ArrayLike,
    *,
    model: str = 'johnson_champoux_allard',
    fluid: Fluid = ...,
) -> PorousMediumResult

The equivalent fluid of this specimen.

The characteristic lengths are stored in the micrometres the tables print and converted, here and once, to the metres johnson_champoux_allard takes.

Parameters

Returns: A PorousMediumResult.

Raises

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

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

PorousMaterial.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).