Source: https://jmrplens.github.io/phonometry/reference/api/materials/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. Two catalogues, because the same page prints two quantities ------------------------------------------------------------ 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`](/phonometry/reference/api/materials/measured/#published_absorption) and [`PUBLISHED_ABSORPTION_AREAS`](/phonometry/reference/api/materials/measured/#published_absorption_areas), and the data file tells them apart by the fields each row carries. The band is the field --------------------- 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`](/phonometry/reference/api/io/io/#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`](/phonometry/reference/api/io/io/#cataloguerowwhy_missing) answers for a band the way it answers for a modulus. [`AbsorptionSpectrum.bands`](/phonometry/reference/api/materials/measured/#absorptionspectrumbands) and [`AbsorptionSpectrum.spectrum`](/phonometry/reference/api/materials/measured/#absorptionspectrumspectrum) give the row back as a spectrum for the caller who wants one. What the numbers are worth -------------------------- 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`](/phonometry/reference/api/materials/measured/#absorptionspectrum) 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. ## ABSORPTION_BANDS_HZ *Constant* (`tuple`). ```python ABSORPTION_BANDS_HZ = (63, 125, 250, 500, 1000, 2000, 4000, 8000) ``` ## absorption_named ```python 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** | Name | Description | | :--- | :--- | | `name` | A fragment of the printed name, matched without case. | **Returns:** The rows whose [`AbsorptionSpectrum.name`](/phonometry/reference/api/materials/measured/#absorptionspectrum) contains it, in the order the tables are read, which is empty when no page has one. ## AbsorptionAreaSpectrum ```python 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** | Name | Description | | :--- | :--- | | `absorption_area_63_m2` | Equivalent absorption area in the 63 Hz octave band, in square metres per unit of `per`. | | `absorption_area_125_m2` | The same in the 125 Hz band. | | `absorption_area_250_m2` | The same in the 250 Hz band. | | `absorption_area_500_m2` | The same in the 500 Hz band. | | `absorption_area_1000_m2` | The same in the 1 kHz band. | | `absorption_area_2000_m2` | The same in the 2 kHz band. | | `absorption_area_4000_m2` | The same in the 4 kHz band. | | `absorption_area_8000_m2` | The same in the 8 kHz band. | | `per` | What one unit of the area belongs to, as the page says it: `"person"` for an audience row, `"seat"` for a chair, and a cubic metre of air for the one row Long prints as an absorption per volume, which is the air term of a Sabine sum by another name. | | `name` | The material as the table names it, attribution stripped. | | `variant` | Which specimen or condition this row is, when the page prints several under one name: `"chemically pure"`, `"direction x"`, `"0.68 mm diameter"`. Empty when the page prints one. | | `source` | Document, table, PDF page and printed folio. | | `table` | The data file this row was read from, without the extension, which is also the first half of its key in the catalogue that holds it. | | `basis` | What the source says a value is: a field name, or `"row"` for the whole row, to one of [`CATALOGUE_BASES`](/phonometry/reference/api/io/io/#catalogue_bases). Hopkins marks most of his Poisson ratios "Estimate", and those cells hold `"estimated"`; a datasheet that declares a class under a product standard would hold `"declared"`. A field with no entry takes the row's, and a row with neither is one whose source does not say, which is a different answer from any of the five. `basis_of` reads it. Independent of `derived`: this is what the source claims for a cell, that is what this library computed. | | `approximate` | Fields the page prints with a `~`. Not an estimate and not an interval: a number the author rounded on purpose. | | `derived` | Field to how it was computed, for the ones this library worked out from the cells the page did print. A derived value is never stored as if it had been read, and on every row the library builds it follows again from the row's own cells: `from_printed` writes it, and nothing else in the library does. One a caller passes to the literal constructor is the caller's word, which the row keeps and `printed_fields` leaves out with its value, as it leaves out every derived one. When the printed cells a value rests on do not all have one `basis`, the text names the basis of each, so a modulus worked out from a plate speed and a Poisson ratio Hopkins marks as an estimate says it rests on that estimate. A value converted from the unit the page prints is not derived (`converted` holds it), and neither is one the page gives by reference to another of its rows (`carried` does). | | `converted` | Field to `(figure, unit)`, the page's figure and the unit it is in, for a value this row holds in a unit the page does not use. Ver and Beranek print their damping materials in degrees Fahrenheit and pounds per square inch, and the row holds degrees Celsius and pascals, so `("3e5", "psi")` sits beside a modulus in pascals. The figure is kept as the page writes it, so the cell can always be read back in the page's own terms. The unit is the one the page prints with the figure or over its column. Long prints the figures of his musician bare, and the sabins recorded for them are a reading of the table, which is set in inches and pounds and names sabins on the next row; that row's note says so. A figure a packaged table prints with another SI prefix, such as the megapascals of Rossing Table 15.5, is held in the base unit with no entry here, and the table's `about` says so. | | `carried` | Field to where the page gives it from, for a value the page gives by reference to another of its rows rather than on this one: a cell left blank under a block whose first row prints the figure, as in Ver and Beranek Table 8.7, or a description that reads "Parecido al anterior" and prints no row number, as three rows of Harris Chapter 32 do, which refers to the row above it. The value is the page's, and this says which of its rows gives it. | | `ranges` | `(low, high)` for each field the page prints as an interval rather than a value. One end is `None` only for a bound whose open side the quantity has no limit on; the end the page prints is always a number, and a two-sided interval has two. | | `bounded_above` | The subset of `ranges` the page prints as `< x` or `<= x`, where the low end is a floor and not a measurement. | | `bounded_below` | The subset of `ranges` the page prints as `> x` or `>= x`, where the high end is the ceiling the quantity cannot pass and not a measurement: Cox gives an aerogel a porosity of `>0.75`, and the 1 beside it is what a porosity is, not what anybody measured. A quantity with no such ceiling leaves that end `None` rather than borrowing a number for it: ASHRAE prints `>45` for a duct wall whose radiated sound the background swamped, and a transmission loss has no value it cannot pass, so the open end is empty. It is never an infinity, which is not a number the page has and not a token JSON can carry. | | `reported` | Field to the values the page lists for it, for a cell that prints several with no single one: `"25, 207, 230"` or `"96, 200-450"`, readings from as many studies. Each entry is a number or a `(low, high)` pair. Not a range, because the page did not print one, and not variants, because the page does not say which is which. | | `unquantified` | Field to what the page printed in place of a number, for a cell that is neither empty nor numeric: `"Varies with frequency"`, `"model"`, `"…"` for a row of dots. What the page printed, and never a sentence about why the number is missing: `why_missing` composes that sentence around it, so a caller and a published table both get the cell as it reads on the page. | | `uncertainty` | Field to the plus-or-minus the page prints beside the value, in the same unit. Cox prints an effective flow resistivity of `(540 +/- 92) x 10^3`, and two of his rows print an uncertainty as large as the value itself. What the interval means is not stated on the page, so it is not stated here either: it is the number the page prints beside the value and nothing more. | | `misprinted` | Field to what the page prints there and why it cannot be that, for a cell whose defect is confirmed and registered in `docs/ERRATA.md`. The number is not served, because a catalogue that handed it over would put a value its own registry calls wrong behind every calculation downstream; it is not dropped either, because a reader reproducing the book needs to see what the book says. This is the narrowest of the hedges and the one that costs most to claim: a cell earns it only when the defect follows from the page itself or from something as settled as the molar mass of a named molecule, and never from one book disagreeing with another. | | `not_derivable` | Field to why this library leaves it empty although the arithmetic would reach it. Bies leaves the speed of his aluminium honeycomb panels blank, and the modulus and the density beside it are effective ones, so `sqrt(E/rho)` would put a one-dimensional speed on a panel that has none. A row says so here, and nothing fills the cell afterwards. | | `attributed_to` | Credit for a cell the book takes from someone else. Keyed by field name, or by `"row"` or `"table"` when the credit covers all of one. | | `group` | The heading of the block this row sits under, when the table prints its rows in named groups: Cox files each material under `"Fibrous materials"`, `"Cellular materials"`, `"Granular materials"` or `"Other"`. Empty for a table that prints one list. | | `note` | What the page says about this row beyond its numbers. | A table set in feet prints its areas in sabins, and [`from_printed`](/phonometry/reference/api/io/io/#cataloguerowfrom_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`](/phonometry/reference/api/io/io/#cataloguerow) 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() ```python AbsorptionAreaSpectrum.bands() -> tuple[int, ...] ``` The bands this row prints a value for, in hertz. ### AbsorptionAreaSpectrum.basis_of() ```python AbsorptionAreaSpectrum.basis_of(field_name: str) -> str ``` What the source says this field is, one of [`CATALOGUE_BASES`](/phonometry/reference/api/io/io/#catalogue_bases). The five are `measured`, `declared`, `calculated`, `estimated` and `extended`. **Parameters** | Name | Description | | :--- | :--- | | `field_name` | One of the field names of this class. | **Returns:** The field's own entry in `basis`, else the row's, else the empty string, which means the source does not say. ### AbsorptionAreaSpectrum.from_printed() *classmethod* ```python 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`](/phonometry/reference/api/materials/measured/#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: ```text cells = row.printed_fields() cells["density_kg_m3"] = 2400.0 row = type(row).from_printed(**cells) ``` **Parameters** | Name | Description | | :--- | :--- | | `cells` | The printed cells, as keywords of the class. | **Returns:** The row, with what follows from its cells filled in. **Raises** | Exception | When | | :--- | :--- | | CatalogueError | for a cell the contract refuses; for a `derived` among the cells, which is this method's to write; for a figure under a unit alias that is not a finite number, or that names a cell given under its own name or under another alias as well; and for printed cells a value that follows from them cannot be worked out of, naming the value and the cells. | | TypeError | for a name that is neither a field of the class nor a unit alias of one. | ### AbsorptionAreaSpectrum.is_approximate() ```python AbsorptionAreaSpectrum.is_approximate(field_name: str) -> bool ``` Whether the page prints this field with a `~`. **Parameters** | Name | Description | | :--- | :--- | | `field_name` | One of the numeric field names of this class. | **Returns:** `True` when the page rounded the cell on purpose. ### AbsorptionAreaSpectrum.is_derived() ```python AbsorptionAreaSpectrum.is_derived(field_name: str) -> bool ``` Whether this library computed this field instead of reading it. **Parameters** | Name | Description | | :--- | :--- | | `field_name` | One of the numeric field names of this class. | **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() ```python 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** | Name | Description | | :--- | :--- | | `field_name` | The quantity wanted. | | `wanted_by` | What wants it, named in the message. | **Returns:** The value, as a float. **Raises** | Exception | When | | :--- | :--- | | ValueError | when the page did not print a number there. | ### AbsorptionAreaSpectrum.printed_fields() ```python 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() ```python 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`](/phonometry/reference/api/io/io/#cataloguerowwhy_missing) on that band's field says which it was. ### AbsorptionAreaSpectrum.values_at() ```python 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`](/phonometry/reference/api/io/io/#cataloguerowprinted) refuses it, with what the page had there; it is never read as zero and never filled from its neighbours. **Parameters** | Name | Description | | :--- | :--- | | `frequencies_hz` | Band centre frequencies, in hertz, of any shape. | **Returns:** A new array of the same shape, one value per frequency. **Raises** | Exception | When | | :--- | :--- | | ValueError | for a frequency that is not finite and positive, for one that matches none of the bands, naming the nearest, and for a band this row does not print, naming the row, the band and what the page had in that cell. | ### AbsorptionAreaSpectrum.why_missing() ```python 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** | Name | Description | | :--- | :--- | | `field_name` | One of the numeric field names of this class. | **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** | Exception | When | | :--- | :--- | | AttributeError | for a name this class does not have, because a misspelt field would otherwise answer as if the cell were empty. | ## AbsorptionSpectrum ```python 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`](/phonometry/reference/api/io/io/#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** | Name | Description | | :--- | :--- | | `absorption_coefficient_63` | Sabine absorption coefficient in the 63 Hz octave band, dimensionless, as printed. | | `absorption_coefficient_125` | The same in the 125 Hz band. | | `absorption_coefficient_250` | The same in the 250 Hz band. | | `absorption_coefficient_500` | The same in the 500 Hz band. | | `absorption_coefficient_1000` | The same in the 1 kHz band. | | `absorption_coefficient_2000` | The same in the 2 kHz band. | | `absorption_coefficient_4000` | The same in the 4 kHz band. | | `absorption_coefficient_8000` | The same in the 8 kHz band. | | `mounting` | The test mounting the page prints beside the row, as it prints it: `"A"`, `"E400"`, `"F"`. Long prints one on most rows and says they are the mountings of ASTM C423, A being the specimen laid on the test-room surface, E400 the specimen over a 400 mm airspace and F the duct-liner fixture, and that "the airspace behind the material greatly affects the results", which is why the same board is two rows here when the page prints it on two mounts. Empty for a page that prints no mounting, which is not the same as mounting A. | | `name` | The material as the table names it, attribution stripped. | | `variant` | Which specimen or condition this row is, when the page prints several under one name: `"chemically pure"`, `"direction x"`, `"0.68 mm diameter"`. Empty when the page prints one. | | `source` | Document, table, PDF page and printed folio. | | `table` | The data file this row was read from, without the extension, which is also the first half of its key in the catalogue that holds it. | | `basis` | What the source says a value is: a field name, or `"row"` for the whole row, to one of [`CATALOGUE_BASES`](/phonometry/reference/api/io/io/#catalogue_bases). Hopkins marks most of his Poisson ratios "Estimate", and those cells hold `"estimated"`; a datasheet that declares a class under a product standard would hold `"declared"`. A field with no entry takes the row's, and a row with neither is one whose source does not say, which is a different answer from any of the five. `basis_of` reads it. Independent of `derived`: this is what the source claims for a cell, that is what this library computed. | | `approximate` | Fields the page prints with a `~`. Not an estimate and not an interval: a number the author rounded on purpose. | | `derived` | Field to how it was computed, for the ones this library worked out from the cells the page did print. A derived value is never stored as if it had been read, and on every row the library builds it follows again from the row's own cells: `from_printed` writes it, and nothing else in the library does. One a caller passes to the literal constructor is the caller's word, which the row keeps and `printed_fields` leaves out with its value, as it leaves out every derived one. When the printed cells a value rests on do not all have one `basis`, the text names the basis of each, so a modulus worked out from a plate speed and a Poisson ratio Hopkins marks as an estimate says it rests on that estimate. A value converted from the unit the page prints is not derived (`converted` holds it), and neither is one the page gives by reference to another of its rows (`carried` does). | | `converted` | Field to `(figure, unit)`, the page's figure and the unit it is in, for a value this row holds in a unit the page does not use. Ver and Beranek print their damping materials in degrees Fahrenheit and pounds per square inch, and the row holds degrees Celsius and pascals, so `("3e5", "psi")` sits beside a modulus in pascals. The figure is kept as the page writes it, so the cell can always be read back in the page's own terms. The unit is the one the page prints with the figure or over its column. Long prints the figures of his musician bare, and the sabins recorded for them are a reading of the table, which is set in inches and pounds and names sabins on the next row; that row's note says so. A figure a packaged table prints with another SI prefix, such as the megapascals of Rossing Table 15.5, is held in the base unit with no entry here, and the table's `about` says so. | | `carried` | Field to where the page gives it from, for a value the page gives by reference to another of its rows rather than on this one: a cell left blank under a block whose first row prints the figure, as in Ver and Beranek Table 8.7, or a description that reads "Parecido al anterior" and prints no row number, as three rows of Harris Chapter 32 do, which refers to the row above it. The value is the page's, and this says which of its rows gives it. | | `ranges` | `(low, high)` for each field the page prints as an interval rather than a value. One end is `None` only for a bound whose open side the quantity has no limit on; the end the page prints is always a number, and a two-sided interval has two. | | `bounded_above` | The subset of `ranges` the page prints as `< x` or `<= x`, where the low end is a floor and not a measurement. | | `bounded_below` | The subset of `ranges` the page prints as `> x` or `>= x`, where the high end is the ceiling the quantity cannot pass and not a measurement: Cox gives an aerogel a porosity of `>0.75`, and the 1 beside it is what a porosity is, not what anybody measured. A quantity with no such ceiling leaves that end `None` rather than borrowing a number for it: ASHRAE prints `>45` for a duct wall whose radiated sound the background swamped, and a transmission loss has no value it cannot pass, so the open end is empty. It is never an infinity, which is not a number the page has and not a token JSON can carry. | | `reported` | Field to the values the page lists for it, for a cell that prints several with no single one: `"25, 207, 230"` or `"96, 200-450"`, readings from as many studies. Each entry is a number or a `(low, high)` pair. Not a range, because the page did not print one, and not variants, because the page does not say which is which. | | `unquantified` | Field to what the page printed in place of a number, for a cell that is neither empty nor numeric: `"Varies with frequency"`, `"model"`, `"…"` for a row of dots. What the page printed, and never a sentence about why the number is missing: `why_missing` composes that sentence around it, so a caller and a published table both get the cell as it reads on the page. | | `uncertainty` | Field to the plus-or-minus the page prints beside the value, in the same unit. Cox prints an effective flow resistivity of `(540 +/- 92) x 10^3`, and two of his rows print an uncertainty as large as the value itself. What the interval means is not stated on the page, so it is not stated here either: it is the number the page prints beside the value and nothing more. | | `misprinted` | Field to what the page prints there and why it cannot be that, for a cell whose defect is confirmed and registered in `docs/ERRATA.md`. The number is not served, because a catalogue that handed it over would put a value its own registry calls wrong behind every calculation downstream; it is not dropped either, because a reader reproducing the book needs to see what the book says. This is the narrowest of the hedges and the one that costs most to claim: a cell earns it only when the defect follows from the page itself or from something as settled as the molar mass of a named molecule, and never from one book disagreeing with another. | | `not_derivable` | Field to why this library leaves it empty although the arithmetic would reach it. Bies leaves the speed of his aluminium honeycomb panels blank, and the modulus and the density beside it are effective ones, so `sqrt(E/rho)` would put a one-dimensional speed on a panel that has none. A row says so here, and nothing fills the cell afterwards. | | `attributed_to` | Credit for a cell the book takes from someone else. Keyed by field name, or by `"row"` or `"table"` when the credit covers all of one. | | `group` | The heading of the block this row sits under, when the table prints its rows in named groups: Cox files each material under `"Fibrous materials"`, `"Cellular materials"`, `"Granular materials"` or `"Other"`. Empty for a table that prints one list. | | `note` | What the page says about this row beyond its numbers. | ### AbsorptionSpectrum.absorption_coefficient() ```python AbsorptionSpectrum.absorption_coefficient(band_hz: int) -> float ``` The coefficient in one band, or a refusal that says what the page had. **Parameters** | Name | Description | | :--- | :--- | | `band_hz` | An octave-band centre frequency from [`ABSORPTION_BANDS_HZ`](/phonometry/reference/api/materials/measured/#absorption_bands_hz). | **Returns:** The printed coefficient, as a float. **Raises** | Exception | When | | :--- | :--- | | ValueError | when the page has no number in that band, naming the row, the band and what the cell held instead; or when *band_hz* is not a band any absorption table prints. | ### AbsorptionSpectrum.bands() ```python AbsorptionSpectrum.bands() -> tuple[int, ...] ``` The bands this row prints a value for, in hertz. ### AbsorptionSpectrum.basis_of() ```python AbsorptionSpectrum.basis_of(field_name: str) -> str ``` What the source says this field is, one of [`CATALOGUE_BASES`](/phonometry/reference/api/io/io/#catalogue_bases). The five are `measured`, `declared`, `calculated`, `estimated` and `extended`. **Parameters** | Name | Description | | :--- | :--- | | `field_name` | One of the field names of this class. | **Returns:** The field's own entry in `basis`, else the row's, else the empty string, which means the source does not say. ### AbsorptionSpectrum.from_printed() *classmethod* ```python 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`](/phonometry/reference/api/materials/measured/#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: ```text cells = row.printed_fields() cells["density_kg_m3"] = 2400.0 row = type(row).from_printed(**cells) ``` **Parameters** | Name | Description | | :--- | :--- | | `cells` | The printed cells, as keywords of the class. | **Returns:** The row, with what follows from its cells filled in. **Raises** | Exception | When | | :--- | :--- | | CatalogueError | for a cell the contract refuses; for a `derived` among the cells, which is this method's to write; for a figure under a unit alias that is not a finite number, or that names a cell given under its own name or under another alias as well; and for printed cells a value that follows from them cannot be worked out of, naming the value and the cells. | | TypeError | for a name that is neither a field of the class nor a unit alias of one. | ### AbsorptionSpectrum.is_approximate() ```python AbsorptionSpectrum.is_approximate(field_name: str) -> bool ``` Whether the page prints this field with a `~`. **Parameters** | Name | Description | | :--- | :--- | | `field_name` | One of the numeric field names of this class. | **Returns:** `True` when the page rounded the cell on purpose. ### AbsorptionSpectrum.is_derived() ```python AbsorptionSpectrum.is_derived(field_name: str) -> bool ``` Whether this library computed this field instead of reading it. **Parameters** | Name | Description | | :--- | :--- | | `field_name` | One of the numeric field names of this class. | **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() ```python 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** | Name | Description | | :--- | :--- | | `field_name` | The quantity wanted. | | `wanted_by` | What wants it, named in the message. | **Returns:** The value, as a float. **Raises** | Exception | When | | :--- | :--- | | ValueError | when the page did not print a number there. | ### AbsorptionSpectrum.printed_fields() ```python 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() ```python 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`](/phonometry/reference/api/io/io/#cataloguerowwhy_missing) on that band's field says which it was. ### AbsorptionSpectrum.values_at() ```python 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`](/phonometry/reference/api/io/io/#cataloguerowprinted) refuses it, with what the page had there; it is never read as zero and never filled from its neighbours. **Parameters** | Name | Description | | :--- | :--- | | `frequencies_hz` | Band centre frequencies, in hertz, of any shape. | **Returns:** A new array of the same shape, one value per frequency. **Raises** | Exception | When | | :--- | :--- | | ValueError | for a frequency that is not finite and positive, for one that matches none of the bands, naming the nearest, and for a band this row does not print, naming the row, the band and what the page had in that cell. | ### AbsorptionSpectrum.why_missing() ```python 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** | Name | Description | | :--- | :--- | | `field_name` | One of the numeric field names of this class. | **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** | Exception | When | | :--- | :--- | | AttributeError | for a name this class does not have, because a misspelt field would otherwise answer as if the cell were empty. | ## PUBLISHED_ABSORPTION *Constant* (`mapping`). ## PUBLISHED_ABSORPTION_AREAS *Constant* (`mapping`).