Source code for solprop.physdata.gases

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""The gas species solprop knows about.

:class:`Gas` names every built-in gas, and every material quantity of it comes from
optmat (SEP 3): the linear law, the equation of state and transport, the Kerr
coefficient, the Raman response and the ionisation rate all key off it. :func:`as_gas`
coerces a name, and :func:`is_molecule` and :func:`is_air` classify one. A model variant
is not a separate gas; it is chosen with a
:class:`~solprop.physdata.selection.MaterialSelection`.
"""

from enum import StrEnum

from solprop.exceptions import MaterialError

__all__ = ["Gas", "as_gas", "is_air", "is_molecule"]


[docs] class Gas(StrEnum): """A gas species, spelled as its chemical formula. The members are :class:`str` subclasses, so ``Gas.He == "He"`` and a plain string may be used anywhere a gas is expected; :func:`as_gas` performs the conversion and raises :class:`~solprop.exceptions.MaterialError` for anything unknown. Examples -------- >>> from solprop.physdata import Gas >>> Gas.N2O.value 'N2O' >>> Gas("Ar") is Gas.Ar True """ Air = "Air" He = "He" Ne = "Ne" Ar = "Ar" Kr = "Kr" Xe = "Xe" N2 = "N2" H2 = "H2" D2 = "D2" O2 = "O2" CH4 = "CH4" SF6 = "SF6" N2O = "N2O"
[docs] def as_gas(gas: Gas | str) -> Gas: """Coerce a gas name to a :class:`Gas` member. Parameters ---------- gas : Gas or str A :class:`Gas` member or its exact name, e.g. ``"He"``. The lookup is case-sensitive: an explicit error beats a silent coercion. Returns ------- Gas The matching member. Raises ------ MaterialError If `gas` is not one of the known species. Examples -------- >>> from solprop.physdata import as_gas >>> as_gas("Kr") <Gas.Kr: 'Kr'> """ try: return Gas(gas) except ValueError as exc: known = ", ".join(member.value for member in Gas) raise MaterialError( f"unknown gas {gas!r}; solprop knows {known}", parameter="gas" ) from exc
#: The species whose particles are single atoms. Everything else in :class:`Gas` is #: molecular, including ``Air``, which is a mixture of diatomic molecules. _MONATOMIC = frozenset({Gas.He, Gas.Ne, Gas.Ar, Gas.Kr, Gas.Xe})
[docs] def is_molecule(gas: Gas | str) -> bool: """Return whether the species is molecular rather than a single atom. ``Air`` counts as molecular: it is a mixture of diatomic molecules, not a monatomic gas. The predicate is chemical only; which ionisation rate and which Raman response a gas has is optmat's (:mod:`solprop.nonlinear.optmat_rates`, :mod:`solprop.nonlinear.optmat_raman`). Parameters ---------- gas : Gas or str A :class:`Gas` member or its exact name. Returns ------- bool True for a molecular species, False for a noble gas. Raises ------ MaterialError If `gas` is not one of the known species. Examples -------- >>> from solprop.physdata import is_molecule >>> is_molecule("He"), is_molecule("N2"), is_molecule("Air") (False, True, True) """ return as_gas(gas) not in _MONATOMIC
[docs] def is_air(material: Gas | str) -> bool: """Return whether a built-in gas's name means air. Unlike :func:`as_gas`, which is case-sensitive, this accepts the spelling the interface takes for air: ``"air"`` in any case, with surrounding whitespace ignored. Any other name, known or not, is simply not air; nothing is refused. Parameters ---------- material : Gas or str The name given to the interface. Returns ------- bool ``True`` for ``Gas.Air`` and for ``"air"`` in any case. Examples -------- >>> from solprop.physdata import Gas, is_air >>> is_air(Gas.Air), is_air(" AIR "), is_air("Ar") (True, True, False) """ if isinstance(material, Gas): return material is Gas.Air return material.strip().lower() == "air"