fluids.catalogue

Fluid states read from a printed page.

A density and a speed of sound stand behind every level this library computes, and most of them are computed: air, ideal_gas and sea_water take the conditions that were measured and return the state that follows. A few are not. Some books print a table of fluids the way they print a table of solids, a density and a speed of sound at a stated temperature, and those are read rather than derived. This is where they live.

The distinction is carried in model, which every state already uses to say what produced it. A computed state names the closed form, the annex or the fit; a state from here names the table, with its PDF page and its printed folio, because the table is what produced it and a reader checking the number needs the page rather than the name of an equation that was never used. The citation lives once, in the data file beside the rows, the same shape the solid and porous catalogues use.

Four more sit elsewhere in the tree, each beside the model or the standard that fixes it, and they disagree: the absorber models propagate through 343 m/s at 1,205 kg/m3, the airflow-resistance annex through 345,87 at 1,186, EN/ISO 12354 through 340 at 1,29, and the acoustic solver defaults to 343 at 1,2. None of them is wrong. Each is the air its own document assumes, and substituting one for another would change a number that document prints, which is why each stays with the clause that prints it rather than being gathered here.

Gathering them would also invert the dependency this package exists at the bottom of: fluids is part of the transverse toolbox precisely so that any domain may import it, and a catalogue here that imported materials, building and simulation to reach them would make the medium depend on three of the domains that stand on it. The comparison a reader wants is a documentation artefact, and it is built as one: the published-catalogues page of the site lists all of them side by side, gathered by a script that is free to see the whole tree.

A book that prints a table of gases prints something different from a table of fluids: not a density and a speed of sound, which a gas only has once a temperature and a pressure are named, but the ratio of specific heats and the molar mass, which close the ideal-gas state at any temperature and pressure. So the gases live in a catalogue of their own, PUBLISHED_GASES, and reach a state through Gas.ideal_state, which is ideal_gas with the citation carried along. Air appears in both, and it should: Bies prints it once as a state at 20 degC and once as a pair of constants, and those are two different readings of the same gas.

It is not a table of fluid properties to look values up in. Air at 23 degC and 50 per cent relative humidity is air, which computes it from the conditions that were measured; sea water is sea_water. Use a row here to reproduce a book’s own number.

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

Gas(
    *,
    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 = '',
    molar_mass_kg_mol: float | None = None,
    heat_capacity_ratio: float | None = None,
)

One gas of a published table: the two numbers that close its state.

A table of gases does not print a density and a speed of sound, because a gas does not have one: it has whichever the temperature and the pressure give it. What it prints instead is the pair that fixes the whole family, the ratio of specific heats and the molar mass, and ideal_state walks from that pair to the ideal-gas state at whichever temperature and pressure the caller asks for. That is the difference between this catalogue and PUBLISHED_FLUIDS, which holds states: a row there is one condition a book measured, a row here is every condition its two constants close under the ideal-gas relations.

The hedges of CatalogueRow apply unchanged. A cell printed as an interval is a range and not a value, which is what saturated steam is in the table this reads first.

Attributes

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

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

Gas.ideal_state(
    *,
    temperature_c: float,
    static_pressure_pa: float | None = None,
) -> Fluid

The gas at one state, through the ideal-gas closure.

Parameters

Returns: The Fluid the two printed constants give at that state, carrying this row’s citation in its model so the state can be traced back to the page.

Raises

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

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

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

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

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

gases_named(name: str) -> tuple[Gas, ...]

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

Two books printing one gas is worth having, because the pair they print is not always the same pair: for carbon dioxide one of them gives 1,30 and the other 1,33. That is 2,3 per cent on the ratio and, since the speed of sound goes as its square root, 1,2 per cent on the speed, which a reader deserves to see both sides of rather than whichever this library happened to load first.

Parameters

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

Constant (mapping).

Constant (mapping).