Species data#

A gas species is described by a Species: its linear susceptibility, its Kerr hyperpolarisability, its ionisation data, its Raman response if it has one, and the equation of state that turns a partial pressure and a temperature into a number density. Species are the members of a gas mixture (gas mixtures).

The factory solprop.physdata.species("Ar") builds a built-in gas from optmat: its linear susceptibility, with optmat’s equation of state and transport properties (OptmatGas), its Kerr model, evaluated at a run’s carrier by kerr_coefficient() (OptmatKerr), and its first ionisation energy (ionisation_potential()); its rate and Raman response are optmat’s, resolved by the drivers. selection= (a MaterialSelection) names another of optmat’s models (see material selection). A Species passed to it is returned unchanged, so any function that takes a species also takes a custom one built from the classes below: for example a TabulatedSusceptibility of measured refractivity and absorption, with the IdealGas equation of state, and its own Raman constants as a MolecularRaman.

Because the factory has the same name as its module, solprop.physdata.species refers to the function, not the module; the module’s classes and its other public functions are documented on this page. The classes and ionisation_potential are importable from solprop.physdata.

class solprop.physdata.species.Species(name, susceptibility, equation_of_state=<factory>, gamma3=None, ionisation=None, raman=None, citation='', kerr=None)[source]#

Bases: Displayed

Describe one chemical species and the response data it supplies.

Attributes:

namestr: Non-empty species name, used as the default component label.
susceptibilityGasSusceptibility or TabulatedSusceptibility: Linear susceptibility per particle in m^3.
equation_of_stateEquationOfState: Partial-pressure equation of state; ideal gas unless supplied.
gamma3float or None: A caller’s third-order hyperpolarisability in m^5/V^2, one number at every wavelength; absent data is explicit. None beside a kerr model, and for every built-in gas.
ionisationIonisationData or None: The energy per ionisation event, when available: optmat’s for a built-in gas, the caller’s otherwise.
ramanMolecularRaman or None: A caller’s molecular Raman constants; None for a built-in gas, whose response is optmat’s (solprop.nonlinear.optmat_raman).
citationstr: Provenance of custom data.
kerrOptmatKerr or None: optmat’s dispersive Kerr model, evaluated at a run’s carrier (kerr_coefficient()) instead of a fixed gamma3; None for supplied data. A run’s record carries it through the species’ material_records, not through the configuration.

citation: str = ''#

equation_of_state: EquationOfState#

gamma3: float | None = None#

ionisation: IonisationData | None = None#

kerr: OptmatKerr | None = None#

kerr_coefficient(wavelength=None)[source]#

Return the per-particle Kerr coefficient at a carrier wavelength.

Parameters:

wavelengthfloat or None, optional: The run’s vacuum carrier wavelength in m. Required for an optmat kerr model, which is dispersive; ignored by a fixed gamma3.

Returns:

float or None: gamma3 in m^5/V^2, or None for a species with no Kerr data.

Raises:

MaterialError: If the species has an optmat model and no carrier is given.

Examples

>>> from solprop.physdata import species
>>> f"{species('Ar').kerr_coefficient(800e-9):.6e}"
'1.476195e-51'

property material_records: tuple[MaterialRecord, ...][source]#

Return the records of the optmat models the species carries.

Returns:

tuple of MaterialRecord: The linear model’s and the equation of state’s, then the transport models’, then the Kerr model’s; empty for a species of supplied data.

name: str#

raman: MolecularRaman | None = None#

susceptibility: GasSusceptibility | TabulatedSusceptibility#

class solprop.physdata.species.EquationOfState(*args, **kwargs)[source]#

Bases: Protocol

Convert a species’ partial pressure and temperature to number density.

density(pressure_bar, temperature)[source]#

Return number density in m^-3.

Parameters:

pressure_barfloat: Non-negative partial pressure in bar.
temperaturefloat: Positive temperature in K.

Returns:

float: Number density in m^-3.

pressure(number_density, temperature)[source]#

Return partial pressure in bar.

Parameters:

number_densityfloat: Non-negative number density in m^-3.
temperaturefloat: Positive temperature in K.

Returns:

float: Partial pressure in bar.

class solprop.physdata.species.IdealGas[source]#

Bases: object

Use the ideal-gas equation of state for a partial population.

density(pressure_bar, temperature=293.15)[source]#

Return ideal-gas number density.

Parameters:

pressure_barfloat: Non-negative partial pressure in bar.
temperaturefloat, optional: Positive temperature in K.

Returns:

float: Number density in m^-3.

Raises:

MaterialError: If pressure or temperature is non-finite or outside its domain.

pressure(number_density, temperature=293.15)[source]#

Return ideal-gas partial pressure.

Parameters:

number_densityfloat: Non-negative number density in m^-3.
temperaturefloat, optional: Positive temperature in K.

Returns:

float: Partial pressure in bar.

Raises:

MaterialError: If density or temperature is outside its domain.

class solprop.physdata.species.OptmatGas(gas)[source]#

Bases: object

Take a gas’s equation of state and transport properties from optmat.

The density is optmat’s real-gas law N = p / (Z k_B T) and the pressure its exact inverse, on the gas’s phase domain: below saturation, or above the critical temperature. A condensed state is refused, naming the saturation pressure. Vacuum is exact: zero pressure is zero density and back, without calling optmat. Gas.Air takes CoolProp’s pseudo-pure dry air (optmat’s air_equation_of_state) for its density, and the constituents of optmat’s "dry air (N2, O2, Ar)" for its transport properties.

The transport properties are optmat’s dilute viscosity, ideal-gas heat capacity and molar mass, each over its own temperature range; solprop.gasflow takes them for a fill of species that carry this equation of state.

Pressures are in bar at this interface; optmat receives pascals.

Attributes:

gasGas: The species.

Examples

>>> from solprop.physdata.species import OptmatGas
>>> argon = OptmatGas("Ar")
>>> f"{argon.density(1.0, 293.15):.6e}"
'2.472418e+25'
>>> argon.density(0.0, 293.15)
0.0
>>> f"{argon.pressure(argon.density(3.0, 293.15), 293.15):.12f}"
'3.000000000000'

property constituents: tuple[tuple[str, float], ...][source]#

Return the gases and mole fractions the transport properties combine.

Returns:

tuple: (gas, mole fraction) pairs: the gas itself, or air’s constituents.

density(pressure_bar, temperature=293.15)[source]#

Return the real-gas number density at a partial pressure.

Parameters:

pressure_barfloat: Non-negative partial pressure in bar; zero is vacuum.
temperaturefloat, optional: Positive temperature in K.

Returns:

float: Number density in m^-3; exactly 0 at zero pressure.

Raises:

MaterialError: If the pressure or temperature is outside its domain, or the state is condensed or outside the equation’s range.

gas: Gas | str#

property key: Gas[source]#

Return the species as a registry member.

Returns:

Gas: The gas.

property material_records: tuple[MaterialRecord, ...][source]#

Return the records of the equation of state and transport models.

Returns:

tuple of MaterialRecord: The equation of state first, then each constituent’s transport model.

molar_heat_capacity(temperature)[source]#

Return the ideal-gas isobaric molar heat capacity, mole-weighted for air.

Parameters:

temperaturefloat: Temperature in K, within temperature_range.

Returns:

float: c_p in J mol^-1 K^-1.

Raises:

MaterialError: If the temperature is outside the range.

property molar_mass: float[source]#

Return the molar mass of the fluid whose equation of state gives the density.

optmat’s equation of state’s own (EquationOfState.molar_mass), so that a mass density formed from density() is the equation’s: for a pure gas it equals the transport model’s, and for Gas.Air it is CoolProp’s pseudo-pure dry air’s, 0.02896546 kg/mol, not the mean of the N2/O2/Ar constituents (0.0289597), which enters only Wilke’s viscosity rule.

Returns:

float: Molar mass in kg mol^-1.

pressure(number_density, temperature=293.15)[source]#

Return the partial pressure at a number density, the density’s inverse.

Parameters:

number_densityfloat: Non-negative number density in m^-3; zero is vacuum.
temperaturefloat, optional: Positive temperature in K.

Returns:

float: Partial pressure in bar; exactly 0 at zero density. It reproduces the density to optmat’s round-trip tolerance, 1e-12 relative.

Raises:

MaterialError: If the density or temperature is outside its domain, or the gas reaches the density only condensed.

sound_speed(pressure_bar, temperature)[source]#

Return the real gas’s speed of sound from its equation of state.

Parameters:

pressure_barfloat: Pressure in bar, > 0.
temperaturefloat: Temperature in K, within temperature_range.

Returns:

float: Speed of sound in m s^-1.

Raises:

MaterialError: If the pressure is not positive, or the state is outside the domain.

property temperature_range: tuple[float, float][source]#

Return the temperatures over which every transport property is defined.

Returns:

tuple of float: The lowest and highest temperature in K, over every constituent’s viscosity and heat capacity.

viscosity(temperature)[source]#

Return the dilute viscosity; Wilke’s rule over air’s constituents.

Parameters:

temperaturefloat: Temperature in K, within temperature_range.

Returns:

float: Dynamic viscosity in Pa s.

Raises:

MaterialError: If the temperature is outside the range.

Warns:

MaterialStatusWarning: If a transport model is provisional (optmat’s CH4 viscosity).

class solprop.physdata.species.IonisationData(potential, citation='')[source]#

Bases: object

Carry the energy a plasma response pays per ionisation event of a species.

A built-in gas carries optmat’s curated first ionisation energy (ionisation_potential()); a caller’s species carries its own. The rate itself is never derived from it: it is optmat’s (OptmatRate) or the caller’s (SEP 3, D1).

Attributes:

potentialfloat: Positive first ionisation potential in J.
citationstr: Provenance of the value.

citation: str = ''#

potential: float#

class solprop.physdata.species.TabulatedSusceptibility(omega, refractivity, absorption_cross_section, wavelength_range, citation='')[source]#

Bases: object

Interpolate measured dilute refractivity and absorption with explicit SI units.

The real susceptibility per particle is twice the supplied refractivity per density. The imaginary part is c * absorption_cross_section / omega. This conversion describes dilute optical data; the medium subsequently forms the exact square root of its summed susceptibility. Extrapolation is refused.

Attributes:

omeganumpy.ndarray: Strictly increasing positive angular frequencies in rad/s.
refractivitynumpy.ndarray: Real (n - 1) / rho in m^3, at each supplied frequency.
absorption_cross_sectionnumpy.ndarray: Non-negative intensity absorption cross-section in m^2.
wavelength_rangetuple of float: Declared shortest and longest supported wavelength in m, within the table.
citationstr: Source and measurement conditions of the supplied optical data.

absorption_cross_section: Float[ndarray, 'n_absorption']#

citation: str = ''#

dsusceptibility_domega(omega)[source]#

Differentiate the optical interpolant analytically.

Parameters:

omegaarray_like or float: Positive angular frequencies in rad/s, within the declared support.

Returns:

numpy.ndarray: Frequency derivative in m^3 s, with the input shape.

Raises:

MaterialError: If a requested frequency is outside the declared support.

omega: Float[ndarray, 'n_samples']#

refractivity: Float[ndarray, 'n_refractivity']#

property source: str[source]#

Return the source name used in material diagnostics.

Returns:

str: The explicit tabulated-data source name.

susceptibility(omega)[source]#

Return complex per-particle susceptibility within the declared support.

Parameters:

omegaarray_like or float: Positive angular frequencies in rad/s, within the declared support.

Returns:

numpy.ndarray: Complex susceptibility per particle in m^3, with the input shape.

Raises:

MaterialError: If a requested frequency is outside the declared support.

wavelength_range: tuple[float, float]#

solprop.physdata.species.ionisation_potential(gas)[source]#

Return a built-in gas’s first ionisation energy, optmat’s curated value.

The energy a plasma response pays per event when its rate declares none of its own; an optmat rate pays the energy its own exponent uses instead (SEP 3, D8).

Parameters:

gasGas or str: A built-in gas other than air.

Returns:

float: The first ionisation energy in J (adiabatic, as optmat curates it).

Raises:

MaterialError: If the gas is unknown or is air.

Examples

>>> from solprop.physdata import ionisation_potential
>>> f"{ionisation_potential('Ar'):.6e}"
'2.524968e-18'