solids.catalogue

Solid materials as one published table prints them.

A caller who needs a Young’s modulus for plasterboard has two bad options and one good one. They can type a number they half remember, or they can open a book and copy a row by hand into their script, which is the same thing with extra steps. The good one is to read the row from a catalogue that says which page it came from, and that is what this module is.

A materials table is not a list of measurements. Hopkins Table A2 marks most of its Poisson ratios and internal loss factors with a footnote that reads, in full, “Estimate”, and it prints some of its densities as a range rather than a number, some of its loss factors as an upper bound, and one of its wave speeds with a note that the material is orthotropic and the figure quoted is an effective value. A catalogue that flattened all of that into floats would be claiming twenty-five measured Poisson ratios where the page offers four.

So every row carries what the cell actually said: SolidMaterial.basis holds "estimated" for each field the page marks as an estimate, which basis_of reads back, SolidMaterial.ranges carries the seven cells printed as an interval (two densities, two speeds and three loss factors), SolidMaterial.bounded_above names the two of those loss factors the page prints as an upper bound rather than a band, and SolidMaterial.attributed_to carries the per-cell credit for the rows whose columns come from different authors. A field the table leaves empty is None and not a guess.

In solids/data/hopkins-2007-table-a2.json, one record per material, read at import through the package-data reader in phonometry._internal. Rows are data: keeping them in a file means a second table is a second file rather than a longer literal, means a changed digit is one line of a diff, and means the citation is written once, in the file that holds the rows it belongs to. The provenance gate reads it from there too, so the comment above the constant and the page it names cannot drift apart.

It is not a specification. Block densities vary by manufacturer, boards vary by batch, and Hopkins says as much by printing ranges where a range is what is known. Use a row to reproduce a worked example, to sanity-check a measurement, or to get an order of magnitude; use a measurement 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.

Constant (mapping).

SolidMaterial(
    *,
    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 = '',
    density_kg_m3: float | None = None,
    youngs_modulus_pa: float | None = None,
    shear_modulus_pa: float | None = None,
    poisson_ratio: float | None = None,
    longitudinal_speed_m_s: float | None = None,
    bar_longitudinal_speed_m_s: float | None = None,
    plate_longitudinal_speed_m_s: float | None = None,
    bulk_longitudinal_speed_m_s: float | None = None,
    transverse_speed_m_s: float | None = None,
    loss_factor: float | None = None,
    flexural_loss_factor: float | None = None,
    longitudinal_loss_factor: float | None = None,
    in_situ_loss_factor: float | None = None,
    thickness_critical_frequency_product_m_hz: float | None = None,
    borrowed: Mapping[str, str] = ...,
)

One row of a published materials table, with what the cell said.

Every quantity is optional, because no two of the books this catalogue reads print the same columns: Hopkins gives a plate speed and no modulus, Mechel a modulus and no speed, Cremer both plus a shear modulus, Arau neither. A field is None when the page had nothing to put there, and why_missing says what it had instead.

The three longitudinal speeds are three fields, and a fourth holds the one a page prints without saying which it is. They are three different waves and the books do not agree on what to call them. Cremer’s c_LII and Bies’ sqrt(E/rho) are the bar speed; Hopkins’ quasi-longitudinal is the plate speed; and the bulk speed is neither. At nu = 0.3 the plate speed is 4.8 per cent above the bar speed and the bulk speed is 16 per cent above it, which is the figure Cremer prints under his Eq. (3.32) with the warning that it matters which one is meant. One field holding whichever the page happened to print is the mistake this catalogue exists to prevent, so there is no field that means “whichever one the page happened to print”. longitudinal_speed_m_s is not that: it means the page printed a longitudinal speed and said nothing about which, which is a statement about the source rather than a shrug about the wave.

The loss factors are four fields for the same reason. A flexural loss factor is measured in bending and a longitudinal one is not; an in-situ one is not a property of the material at all, but of a panel installed in a building, support and radiation included; and a page that prints one without saying which it is has said something weaker than any of the three, which is what loss_factor holds.

The name, the citation, the variant and the hedges a cell can carry instead of a number (basis, ranges, reported, unquantified, approximate, derived, converted, carried, attributed_to) are the ones every catalogue row has; one is this catalogue’s own and is described below. A cell the page marks as an estimate holds "estimated" in SolidMaterial.basis, and row.basis_of(field) == "estimated" is the question to ask before reading it as a measurement, which is the mistake this catalogue exists to prevent.

Attributes

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

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

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

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

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

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

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

solids_named(name: str) -> tuple[SolidMaterial, ...]

Every published row for a material, across the books.

Comparing two books is the point of holding both, and it has to be a deliberate act: a lookup that returned one row for “steel” would be choosing between published values on the caller’s behalf.

Parameters

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