Humid air

A reciprocity calibration needs the air it is done in to five or six figures, which is why the standard that defines that calibration also carries the most carefully stated model of humid air in the acoustic literature. Annex F is that model, and this page is what the library does with it.

from phonometry import fluids

f = fluids.air(
    temperature_c=23.0,
    static_pressure_pa=101325.0,
    relative_humidity_percent=50.0,
)
print(f.density)                    # 1.1860847889882964 kg/m3
print(f.speed_of_sound)             # 345.86651725321 m/s
print(f.characteristic_impedance)   # 410.2270151343906 Pa.s/m

Those are the conditions of the first row of Table F.1, and the numbers are the ones the annex prints. Every one of the ten figures it tabulates comes back inside the rounding of its last printed digit.

The library asks for the temperature and assumes the other two. That is not laziness in one direction and rigour in the other; it follows from how much each is worth. Sweeping each condition across its plausible range, with the annex’s own equations:

The pressure dominates, and it is also the one people believe they already know. A test site 1000 metres up sits at roughly 90 kPa. That is 11 % below the standard atmosphere the library would otherwise assume, and it puts the density about 13 % high, which is half a decibel on a sound power level with nothing on the page to say so.

Humidity is the opposite case. It moves the density least, and almost nobody knows theirs without measuring it.

So both are assumed and both are announced, once, in the same warning:

import warnings

from phonometry import fluids

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    fluids.air(temperature_c=20.0)

print(caught[0].category.__name__)              # FluidAssumptionWarning
print(str(caught[0].message))
# air() assumed 101325 Pa and 50 % relative humidity. The pressure is the one
# worth measuring: a site 1000 m up sits near 90 kPa, and taking it for one
# standard atmosphere puts the density about 13 % high. The whole span of
# humidity, 0 % to 100 %, is worth about 1 % of the density. Pass the
# conditions to silence this.

One warning, not two, because a caller who supplied neither has one thing to fix rather than two.

Supplying both is silent, which is the property somebody who measured their air should get. Python shows the warning once per call site, so exploring at a prompt is not drowned in it, and it derives from PhonometryWarning, so one rule escalates it to an error for anyone who wants their runs to fail rather than warn:

import warnings

from phonometry import PhonometryWarning

warnings.filterwarnings("error", category=PhonometryWarning)

The temperature has no default at all. It is the one condition a caller has actually measured, and there is no value that would be defensible to invent for it.

The carbon dioxide fraction defaults quietly, to 0,000 4. That is not a guess about the caller’s air: Clause F.2 names it as the value to use for laboratory conditions in the absence of a measurement, so the library is quoting the annex rather than filling a hole.

Table F.1 prints five quantities. Clause F.6 gives expressions for two more, and three follow by identity from the ones above:

f.density                    # printed by Table F.1
f.speed_of_sound             # printed, at zero frequency
f.heat_capacity_ratio        # printed
f.viscosity                  # printed
f.thermal_diffusivity        # printed
f.thermal_conductivity       # Clause F.6 expression
f.specific_heat_capacity     # Clause F.6 expression
f.characteristic_impedance   # rho c
f.prandtl_number             # eta / (rho alpha_t)
f.kinematic_viscosity        # eta / rho

A quantity this model did not determine raises rather than returning a number nobody printed. The error names the model, what it does determine, and the two ways out:

from phonometry.fluids import Fluid, FluidPropertyUnavailable

measured = Fluid(
    temperature_c=10.0,
    static_pressure_pa=1.1e6,
    composition={"salinity_psu": 35.0},
    model="a density and a sound speed, measured",
    validity="",
    properties={"density": 1027.0, "speed_of_sound": 1491.0},
)
try:
    measured.heat_capacity_ratio
except FluidPropertyUnavailable as exc:
    print(exc)
# 'a density and a sound speed, measured' does not determine
# 'heat_capacity_ratio'; it determines density, speed_of_sound. Supply the
# quantity yourself, or use a model that prints it.

That looks like pedantry with one fluid in the library, and stops looking like it with two: sea water has no ratio of specific heats to give, and a Fluid that invented one would be handing a caller a number with the shape of a measurement and none of the substance.

Three attributes are not quantities and never raise. They are the record of where the numbers came from:

f.properties          # exactly what this model determined
f.model               # 'IEC 61094-2:2009 Annex F (CIPM-2007)'
f.composition         # the humidity and CO2 it was computed with

Annex F states, on its own page, where its equations were validated: 15 °C to 27 °C, 60 kPa to 110 kPa, 10 % to 90 % relative humidity. It states no range for the carbon dioxide fraction.

Outside that box the library warns and still answers:

import warnings

from phonometry import fluids

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    hot = fluids.air(temperature_c=60.0, static_pressure_pa=101325.0,
                     relative_humidity_percent=50.0)

print(caught[0].category.__name__)                    # FluidWarning
print("temperature 60 degC (stated 15 to 27)" in str(caught[0].message))  # True
print(round(hot.speed_of_sound, 2))                   # 371.52

The distinction matters and it is the rule the whole library follows. Air at 60 °C in a duct exists; a fit past its validated range is still arithmetic, and refusing it would refuse a real measurement. What is refused is a state that cannot be, and that is the whole list: a temperature at or below absolute zero, a pressure that is not positive, a relative humidity outside 0 % to 100 %, a carbon dioxide mole fraction outside 0 to 1, and a non-finite value for any of the four. Each raises ValueError naming the argument.

The oracle is Table F.1: five quantities at two condition sets, ten figures in all. The tolerance is not chosen. A value is stated to within half a unit of the last place it was printed to, so that is what reproducing it means, and the test derives that bound from the printed string rather than carrying a constant somebody picked. It is the last place that sets the bound, not a count of significant figures: 1,186 084 8 carries eight of them and 2,115 317 x 10^-5 seven, and the same rule reads both:

from decimal import Decimal

def half_of_the_last_printed_figure(printed: str) -> float:
    """Half a unit in the last place the annex printed."""
    exponent = int(Decimal(printed).as_tuple().exponent)
    return float(Decimal(5) * Decimal(10) ** (exponent - 1))

half_of_the_last_printed_figure("1.1860848")    # 5e-08
half_of_the_last_printed_figure("2.115317e-5")  # 5e-12

Three conformance rows record how much of that allowance each set uses: 55 % for the first, 96 % for the second, and none at all for the identity that ties the thermal conductivity and the specific heat capacity to the diffusivity printed between them. The 96 % is the density of the second set, and it is the annex’s own rounding rather than any slack of the library’s. Reporting it as a percentage means that if a change ever pushes it out, it is visible coming.

Passing a Fluid to a measurement function is the subject of the packages that consume it, and it comes with a rule worth stating here: where a standard fixes the air of its own procedure, using better air is a departure from the standard, and the library says so rather than letting a measurement quietly stop reproducing the document it cites.

That is why the simplified air formulas of ISO 10534-2, ASTM E2611 and ISO 17497-1 stay in their own modules with their own clauses, and why the Johnson-Champoux-Allard Prandtl number of 0,71 stays frozen at 0,71 even though the air at that state has 0,728.

Two states of that air are published as constants, because a caller has no business writing them out twice. materials.ANNEX_A_AIR is the reference state ISO 9053-2:2020 Annex A.3 fixes for an airflow-resistance measurement, 23 °C and 50 % relative humidity at one standard atmosphere, evaluated through the same CIPM-2007 model as any other air. simulation.SIMULATION_AIR is the solver’s default medium, and it is deliberately not that: 343 m/s and 1,2 kg/m³ flat, the round pair a finite-difference grid is set up with, carried as a Fluid so that a run says which air it was made in rather than leaving two floats standing side by side in a call.