optmat.gas.models.compact#

Compact infrared terms for the molecular fits (OEP 2).

A molecular fit (fit/<gas>) carries its vibrational bands as fixed poles: thousands for CO2 and N2O. Its compact model, compact/<gas>, keeps the fit’s electronic terms, covariance and rotational system unchanged and replaces the vibrational poles by a few effective ones, derived from the stored fit by a constrained least-squares fit to their contribution over the compact model’s intervals. Two moments of the bands are kept exactly: the optical-side limit M_0 = sum f and the static contribution M_-2 = sum f / E^2.

The intervals are the parent’s qualified intervals inside its optical range (range_nm), optionally ending at a configured wavelength (longest_nm); the infrared windows beyond are left to the parent (OEP 2, Part II). Every compact pole is bounded to an absorbing region, between two intervals or outside all of them, so none can lie inside an interval. The fit is weighted by the parent’s absolute statistical one-sigma of alpha, D_2 and D_3 (D_m = d^m (omega alpha) / d omega^m), and the reduction is accepted when every residual on a four-times finer check grid is below the configured fraction of that sigma.

The reduction’s settings are data/gas/compact/<gas>.toml; tools/fit/compact.py derives and writes data/gas/models/compact/<gas>.json, which compact_models() loads. A compact model is never a default.

Module Attributes

`COMPACT_CONFIG_DIRECTORY`	The reduction configurations, `<gas>.toml`.
`COMPACT_MODEL_DIRECTORY`	The stored compact models, `<gas>.json`.

Functions

`absorbing_regions`(parent, intervals)	Return the absorbing regions of the parent's vibrational poles, by energy.
`coefficients`(gas[, form, pressure, temperature])	Return a compact model's coefficients for print (OEP 2, section 6).
`compact_intervals`(parent[, longest_nm])	Return the compact model's intervals: the parent's inside its optical range.
`compact_models`()	Return every stored compact model, by name.
`compact_record`(parent, config, reduction)	Return a reduction as the stored compact model's record.
`derive`(parent, config)	Derive the compact vibrational poles of a fit.
`format_coefficients`(table)	Return a compact model's coefficients as a Markdown table, to 11 digits.
`load_compact_config`(name)	Load a reduction configuration.
`parent_digest`(parent)	Return the SHA-256 of a stored parent fit.
`pole_dispersion_au`(strengths, energies, ...)	Return each pole's `D_m`: `alpha` for order 0, else `d^m (omega alpha)`.
`reproduction`(model)	Re-evaluate the parent's datasets and validators with the compact poles.
`residuals_sigma`(parent, intervals, ...)	Return the compact poles' residuals against the parent's, in its sigma.
`statistical_sigma_au`(parent, omega)	Return the parent's absolute one-sigma of `alpha`, `D_2` and `D_3`.
`vibrational_terms`(parent)	Return the parent's vibrational poles: its fixed terms after the rotational.

Classes

`CompactCoefficients`(model, parent, ...)	A compact model's coefficients, for print (OEP 2, section 6).
`CompactConfig`(gas, description, parent, poles)	The settings of one reduction (`data/gas/compact/<gas>.toml`).
`CompactModel`(gas, name, citation, ...[, ...])	A fit with its vibrational poles replaced by a few compact ones (OEP 2).
`Reduction`(strengths, energies, region, kept, ...)	A derived set of compact vibrational poles.
`Region`(low, high, strengths, energies)	An absorbing region: frequencies outside every compact interval, with poles.

optmat.gas.models.compact.COMPACT_CONFIG_DIRECTORY: Final = PosixPath('/home/docs/checkouts/optmat/checkouts/7/src/optmat/data/gas/compact')#: The reduction configurations, <gas>.toml.

optmat.gas.models.compact.COMPACT_MODEL_DIRECTORY: Final = PosixPath('/home/docs/checkouts/optmat/checkouts/7/src/optmat/data/gas/models/compact')#: The stored compact models, <gas>.json.

class optmat.gas.models.compact.CompactCoefficients(model, parent, model_digest, parent_digest, form, labels, kinds, wavelengths, strengths, chi0, B, C, constant, pressure, temperature, number_density, intervals, residuals_sigma, stated_error, covariance, covariance_parameters)[source]#

Bases: object

A compact model’s coefficients, for print (OEP 2, section 6).

Terms are in descending energy (ascending wavelength): the electronic ones, then the infrared ones and the rotational term. In the polarizability form alpha(lambda) = chi0 + (e^2 / m_e) sum_k f_k / (omega_k^2 - omega^2), with omega_k = 2 pi c / lambda_k, and the index follows through the package’s density conversion ({doc}`conventions`). In the Sellmeier form, at one state, n - 1 = constant + sum_k B_k lambda^2 / (lambda^2 - C_k): the dilute limit, without Lorentz-Lorenz or the refractivity virial, whose error against the full parent is stated.

Attributes:

modelstr: compact/<gas>.
parentstr: fit/<gas>.
model_digeststr: The compact model’s identity digest.
parent_digeststr: The parent’s identity digest.
formstr: polarizability or sellmeier.
labelstuple of str: The terms’ labels.
kindstuple of str: line, effective, infrared or rotational.
wavelengthstuple of float: lambda_k, vacuum, m.
strengthstuple of float: f_k, dimensionless (the polarizability form; empty otherwise).
chi0float: The constant term of the polarizability, C m^2/V (zero for these molecules).
Btuple of float: The Sellmeier strengths, dimensionless (the Sellmeier form; empty otherwise).
Ctuple of float: The Sellmeier resonances lambda_k^2, m^2 (the Sellmeier form).
constantfloat: The Sellmeier form’s constant, N chi0 / (2 epsilon_0).
pressurefloat or None: The Sellmeier form’s state: pressure, Pa.
temperaturefloat or None: Temperature, K.
number_densityfloat or None: The real-gas number density at that state, m^-3 (optmat.gas.eos).
intervalstuple of tuple of float: Where the coefficients are qualified, vacuum wavelengths, m; between them the gas absorbs.
residuals_sigmaMapping: The reduction’s largest residuals, in the parent’s sigma.
stated_errorMapping: The Sellmeier form’s error against the full parent at its state over the intervals: n_minus_1, the largest relative difference in n - 1, and beta2, the largest difference in the group-velocity dispersion relative to its largest value (a relative difference is unbounded at a zero of beta2). Empty for the polarizability form.
covariancenumpy.ndarray: The covariance of the electronic terms’ printed parameters, covariance_parameters, Birge-scaled as the parent’s.
covariance_parameterstuple of str: What each row of the covariance is: f <label> and lambda <label> (m) in the polarizability form, B <label> and C <label> (m^2) in the Sellmeier form.

B: tuple[float, ...]#

C: tuple[float, ...]#

chi0: float#

constant: float#

covariance: Float[ndarray, 'q q']#

covariance_parameters: tuple[str, ...]#

form: str#

intervals: tuple[tuple[float, float], ...]#

kinds: tuple[str, ...]#

labels: tuple[str, ...]#

model: str#

model_digest: str#

number_density: float | None#

parent: str#

parent_digest: str#

pressure: float | None#

residuals_sigma: Mapping[str, float]#

stated_error: Mapping[str, float]#

strengths: tuple[float, ...]#

temperature: float | None#

wavelengths: tuple[float, ...]#

class optmat.gas.models.compact.CompactConfig(gas, description, parent, poles, longest_nm=None, grid_points=400, check_factor=4, tolerance_sigma=0.1, random_starts=0, seed=1, digest='')[source]#

Bases: object

The settings of one reduction (data/gas/compact/<gas>.toml).

Attributes:

gasGas: The species.
descriptionstr: What the reduction gives.
parentstr: The parent fit, fit/<gas>.
polestuple of int: The number of compact poles in each absorbing region, in ascending energy (absorbing_regions()). A region given at least as many poles as it holds keeps the parent’s poles unchanged; a region given none is represented by the others.
longest_nmfloat or None: Where the compact intervals end, nm; None for the end of the optical range.
grid_pointsint: Fitted points per interval, geometric in wavelength.
check_factorint: The check grid has this many times as many points.
tolerance_sigmafloat: The largest residual allowed, in units of the parent’s sigma.
random_startsint: Log-uniform random starting points, beyond the fixed ones.
seedint: The seed of the random starts.
digeststr: SHA-256 of the configuration file.

check_factor: int = 4#

description: str#

digest: str = ''#

gas: Gas#

grid_points: int = 400#

longest_nm: float | None = None#

parent: str#

poles: tuple[int, ...]#

random_starts: int = 0#

seed: int = 1#

tolerance_sigma: float = 0.1#

class optmat.gas.models.compact.CompactModel(gas, name, citation, wavelength_range, kind, strengths=(), energies=(), labels=(), offset_au=0.0, retardation_au=0.0, absorption=None, n_lines=0, n_fixed=0, covariance=<factory>, reduced_chi2=0.0, record=<factory>, *, status='user', status_reason='', modified=(), base='', intervals=())[source]#

Bases: FittedModel

A fit with its vibrational poles replaced by a few compact ones (OEP 2).

The electronic terms, covariance and rotational system are the parent’s; the trailing fixed terms are the compact poles. Its intervals are the parent’s optical ones: beyond them, the range warning names the parent, which is qualified in its infrared windows.

EVALUATION_VERSION: ClassVar[int] = 1#

property parent: str#

The parent fit’s name.

Returns:

str: fit/<gas>.

property residuals_sigma: dict[str, float]#

The reduction’s largest residuals, in the parent’s sigma.

Returns:

dict of str to float: alpha, D2 and D3 on the check grid.

class optmat.gas.models.compact.Reduction(strengths, energies, region, kept, worst, moment_errors, start, passed)[source]#

Bases: object

A derived set of compact vibrational poles.

Attributes:

strengthstuple of float: The poles’ strengths, ascending in energy.
energiestuple of float: Their energies, hartree.
regiontuple of int: The absorbing region of each pole.
kepttuple of bool: Whether each pole is the parent’s own (a region kept unchanged).
worstdict of str to float: The largest |residual| / sigma on the check grid, per quantity.
moment_errorstuple of float: The relative errors of M_0 and M_-2.
startstr: The starting point the chosen solution came from.
passedbool: Whether every residual is below the tolerance.

energies: tuple[float, ...]#

kept: tuple[bool, ...]#

moment_errors: tuple[float, float]#

passed: bool#

region: tuple[int, ...]#

start: str#

strengths: tuple[float, ...]#

worst: Mapping[str, float]#

class optmat.gas.models.compact.Region(low, high, strengths, energies)[source]#

Bases: object

An absorbing region: frequencies outside every compact interval, with poles.

Attributes:

lowfloat: The region’s lowest parent pole, hartree.
highfloat: Its highest, hartree.
strengthsnumpy.ndarray: The parent’s poles in it: strengths.
energiesnumpy.ndarray: Their energies, hartree, ascending.

energies: Float[ndarray, 'r']#

high: float#

low: float#

strengths: Float[ndarray, 'r']#

optmat.gas.models.compact.absorbing_regions(parent, intervals)[source]#

Return the absorbing regions of the parent’s vibrational poles, by energy.

The frequencies outside every interval divide into the region below the lowest interval’s frequencies, those between two adjacent intervals and the region above the highest (where a fold puts a share of the top band system, OEP 3). Only the regions with parent poles count.

Parameters:

parentFittedModel: The fit.
intervalstuple of tuple of float: The compact intervals, m.

Returns:

tuple of Region: In ascending energy.

Raises:

DataError: If a parent pole lies inside an interval.

optmat.gas.models.compact.coefficients(gas, form='polarizability', *, pressure=None, temperature=None)[source]#

Return a compact model’s coefficients for print (OEP 2, section 6).

Parameters:

gasGas or str: CO, CO2, CH4, N2O or SF6.
formstr, optional: polarizability (the poles, with the package’s density conversion) or sellmeier (n - 1 in the dilute limit at one state).
pressurefloat, optional: The Sellmeier form’s pressure, Pa (within the equation of state’s domain).
temperaturefloat, optional: Its temperature, K.

Returns:

CompactCoefficients: The terms in descending energy, the qualified intervals, the reduction’s residuals and, for the Sellmeier form, its state and stated error.

Raises:

OptmatError: For a gas without a compact model (an atom, H2, D2, N2, O2, O3).
ValueError: For another form, or the Sellmeier form without a state.

Examples

>>> table = coefficients("CO2")
>>> table.kinds[:4], table.kinds[-1]
(('effective', 'effective', 'line', 'line'), 'rotational')
>>> air = coefficients("CO2", "sellmeier", pressure=101325.0, temperature=293.15)
>>> f"{air.number_density:.4e}"
'2.5169e+25'

optmat.gas.models.compact.compact_intervals(parent, longest_nm=None)[source]#

Return the compact model’s intervals: the parent’s inside its optical range.

Parameters:

parentFittedModel: The fit.
longest_nmfloat or None, optional: Where the intervals end instead, nm (inside the optical range).

Returns:

tuple of tuple of float: (low, high) vacuum wavelengths, m, ascending.

Raises:

DataError: If no interval is left.

optmat.gas.models.compact.compact_models()[source]#

Return every stored compact model, by name.

Returns:

dict of str to CompactModel: Models named compact/<gas>.

optmat.gas.models.compact.compact_record(parent, config, reduction)[source]#

Return a reduction as the stored compact model’s record.

Parameters:

parentFittedModel: The fit.
configCompactConfig: The settings.
reductionReduction: The derived poles.

Returns:

dict: JSON-serialisable: the parent’s identity, the settings’ digest, the intervals, the regions, the poles, the moments and the achieved residuals.

optmat.gas.models.compact.derive(parent, config)[source]#

Derive the compact vibrational poles of a fit.

A region given at least as many poles as it holds keeps the parent’s; the others’ poles are searched, taking on the rest of the target and of both moments.

Parameters:

parentFittedModel: The fit.
configCompactConfig: The reduction’s settings.

Returns:

Reduction: The chosen poles: of the candidates from every start, the lowest cost among those meeting the tolerance on the check grid, else the lowest cost.

Raises:

DataError: If the pole counts do not match the regions, or the poles cannot keep both moments.

optmat.gas.models.compact.format_coefficients(table)[source]#

Return a compact model’s coefficients as a Markdown table, to 11 digits.

Eleven significant digits keep the rounding within a hundredth of the parent’s sigma (OEP 2, section 7).

Parameters:

tableCompactCoefficients: The coefficients.

Returns:

str: A caption line and the table, in descending energy; wavelengths in um.

optmat.gas.models.compact.load_compact_config(name)[source]#

Load a reduction configuration.

Parameters:

namestr or pathlib.Path: The gas (data/gas/compact/<gas>.toml) or a path.

Returns:

CompactConfig: The settings.

Raises:

DataError: If the file has unknown keys or a negative pole count.

optmat.gas.models.compact.parent_digest(parent)[source]#

Return the SHA-256 of a stored parent fit.

Parameters:

parentstr: fit/<gas>.

Returns:

str: The digest of data/gas/models/fitted/<gas>.json.

optmat.gas.models.compact.pole_dispersion_au(strengths, energies, omega, order)[source]#

Return each pole’s D_m: alpha for order 0, else d^m (omega alpha).

With omega f / (E^2 - omega^2) = (f / 2) [1 / (E - omega) - 1 / (E + omega)], D_m = (f / 2) m! [(E - omega)^-(m+1) - (-1)^m (E + omega)^-(m+1)] for m >= 1, on either side of the pole.

Parameters:

strengthsnumpy.ndarray: Oscillator strengths.
energiesnumpy.ndarray: Energies, hartree.
omeganumpy.ndarray: Photon energies, hartree.
orderint: 0, or the derivative’s order m >= 1.

Returns:

numpy.ndarray: One row per pole, atomic units.

optmat.gas.models.compact.reproduction(model)[source]#

Re-evaluate the parent’s datasets and validators with the compact poles.

Each fitted dataset and validator goes through the fit’s own observation code at its own wavelengths (harmonics included), with the parent’s fitted scales and partner models fixed (OEP 2, sections 5 and 7).

Parameters:

modelCompactModel: The compact model.

Returns:

dict: Per dataset: n (the values in the compact intervals or at shorter wavelengths), max_sigma (their largest change in their own sigma), chi2_change, and beyond_max_sigma for the values outside (reported, not bounded). A static value (zero frequency) has static_relative.

optmat.gas.models.compact.residuals_sigma(parent, intervals, strengths, energies, points)[source]#

Return the compact poles’ residuals against the parent’s, in its sigma.

Parameters:

parentFittedModel: The fit.
intervalstuple of tuple of float: The compact intervals, m.
strengthssequence of float: The compact vibrational poles: strengths.
energiessequence of float: Their energies, hartree.
pointsint: Points per interval.

Returns:

dict of str to numpy.ndarray: alpha, D2 and D3: (compact - parent) / sigma at each point.

optmat.gas.models.compact.statistical_sigma_au(parent, omega)[source]#

Return the parent’s absolute one-sigma of alpha, D_2 and D_3.

The statistical uncertainty from the covariance, Birge-scaled (OEP 2, section 4).

Parameters:

parentFittedModel: The fit.
omeganumpy.ndarray: Photon energies, hartree.

Returns:

dict of int to numpy.ndarray: By order (0, 2, 3), atomic units.

optmat.gas.models.compact.vibrational_terms(parent)[source]#

Return the parent’s vibrational poles: its fixed terms after the rotational.

Parameters:

parentFittedModel: The fit.

Returns:

tuple of numpy.ndarray: Strengths and energies (hartree).