optmat.gas.fitting#

Fit oscillator-strength models to the curated data.

A fit is specified by a configuration, data/gas/fits/<name>.toml, which names

the model: the resonance lines kept at their spectroscopic energies (NIST), each with a prior on its oscillator strength, and the number of effective oscillators that stand for the rest of the distribution (the higher Rydberg lines and the continuum), above a stated lowest energy;
optional priors on dipole sums (the static polarizability S(-2), the Thomas-Reiche-Kuhn sum S(0));
the datasets fitted, each with its options: a free scale (a dataset whose absolute level is less certain than its shape, like Mansfield & Peck’s helium), an extra relative uncertainty added in quadrature, and a wavelength window;
the datasets used only as validators.

The fit is a generalised least-squares problem in the polarizability (atomic units). Each fitted value contributes (s_d alpha_model(omega) - alpha)/sigma, where s_d is its dataset’s scale: 1, free, or constrained by the dataset’s stated systematic uncertainty (a prior residual (s_d - 1)/sigma_sys). Line strengths enter as (f - f_prior)/sigma_f. Effective strengths and energies are fitted as logarithms so that they stay positive and above the lowest allowed energy.

The parameter covariance is (J^T J)^{-1} at the solution; when the reduced chi-squared exceeds one it is also given scaled by it (the Birge ratio), and the uncertainty band of the polarizability follows by linear propagation.

Module Attributes

`FIT_DIRECTORY`	Fit configurations, `<name>.toml`.
`HARTREE_NM`	Vacuum wavelength of a one-hartree photon, nm (2 pi c / (E_h / hbar)).

Functions

`dumps`(result)	Serialise a fit result as JSON text.
`fit`(config[, data, starts, start])	Fit a configuration's model to its data.
`load_config`(name)	Load a fit configuration.
`observations`(config)	Return the fitted observations of a configuration.
`result_record`(result)	Return a fit result as a JSON-serialisable record.
`validation`(result)	Compare the fit with its validator datasets.

Classes

`DatasetOptions`(key[, free_scale, ...])	How one dataset enters a fit.
`FitConfig`(name, gas, description, lines, ...)	A fit's specification.
`FitResult`(config, model, parameters, covariance)	A fitted model with its uncertainty and statistics.
`Line`(label, wavelength_nm, f_prior, f_sigma)	A resonance line kept at its spectroscopic energy.
`Observation`(key, omega, alpha, sigma, ...[, ...])	The fitted values of one dataset, as polarizabilities in atomic units.

class optmat.gas.fitting.DatasetOptions(key, free_scale=False, extra_relative=0.0, range_nm=(0.0, inf), electric=False, infrared=True, correction_au=None, shape_relative=None, temperature=None)[source]#

Bases: object

How one dataset enters a fit.

Attributes:

keystr: source/dataset.
free_scalebool: Fit the dataset’s scale without a prior.
extra_relativefloat: Relative uncertainty added in quadrature to every value.
range_nmtuple of float: Vacuum-wavelength window of the values used, nm.
electricbool: The values are electric polarizabilities (ab initio theory, dielectric measurements), compared with the model without its chi_0. Cauchy moments are always electric.
infraredbool: The values include the vibrational (infrared) contribution, as measured refractivities and dielectric constants do; False for electronic theory. Only used when the model has infrared terms; Cauchy moments are always electronic.
correction_autuple of float or None: (value, sigma) added to every value, atomic units, with sigma added in quadrature to its uncertainty: a term the values lack and the model includes, such as the zero-point vibrational average of a polarizability computed at the equilibrium geometry.
shape_relativefloat or None: With free_scale: the relative uncertainty of the values’ shape, used in place of the stated one when that states the absolute level (which the free scale absorbs) and the register gives the shape’s own precision.
temperaturetuple of float or None: (measured_k, coefficient, sigma): the values were measured at measured_k (K), and the molecule’s zero-density polarizability changes by coefficient (per K, relative; its uncertainty sigma) with temperature. The values are brought to the fit’s reference_temperature by the factor 1 + coefficient (T_ref - measured_k), and sigma |T_ref - measured_k| is added in quadrature to their relative uncertainty (TC-730).

correction_au: tuple[float, float] | None = None#

electric: bool = False#

extra_relative: float = 0.0#

free_scale: bool = False#

infrared: bool = True#

key: str#

range_nm: tuple[float, float] = (0.0, inf)#

shape_relative: float | None = None#

temperature: tuple[float, float, float] | None = None#

optmat.gas.fitting.FIT_DIRECTORY: Final = PosixPath('/home/docs/checkouts/optmat/checkouts/7/src/optmat/data/gas/fits')#: Fit configurations, <name>.toml.

class optmat.gas.fitting.FitConfig(name, gas, description, lines, effective, effective_min_energy, sum_priors, chi0, fitted, validators, range_nm, digest, starts=6, infrared=(), infrared_max_wavenumber=None, fixed=(), retardation=0.0, reference_temperature=None, absorption=None, band_nodes=None, rotational=(), windows=False, intervals_nm=(), gap_reasons=(), derived_sha256='')[source]#

Bases: object

A fit’s specification.

Attributes:

namestr: The configuration’s file stem, and the fitted model’s name.
gasGas: The species.
descriptionstr: What the fit is for.
linestuple of Line: The fixed-energy resonance lines.
effectiveint: The number of effective oscillators.
effective_min_energyfloat: The lowest energy an effective oscillator may take, hartree.
sum_priorsdict of int to tuple of float: Priors {k: (value, sigma)} on dipole sums S(k), atomic units.
chi0float: The atom’s magnetic susceptibility, atomic units: the model’s refractive polarizability is its electric sum plus chi0.
fittedtuple of DatasetOptions: The datasets fitted.
validatorstuple of DatasetOptions: Datasets compared with the fit but not fitted (with their electric flag).
range_nmtuple of float: The wavelength range over which the fitted model is declared valid, nm.
digeststr: SHA-256 of the configuration file, recorded with the result.
startsint: The number of starting points fit() tries ([model] starts, default 6).
infraredtuple of tuple: Fixed vibrational terms (label, strength, energy in hartree): the gas’s HITRAN bands (optmat.gas.infrared) up to [model] infrared_max_wavenumber; empty if that key is absent.
infrared_max_wavenumberfloat or None: The cutoff, cm^-1.
fixedtuple of tuple: Fixed electronic terms (label, strength, energy in hartree) from [[model.fixed]] (a published distribution’s interval strengths above the measured range, say): always included, outside the fitted parameters.
reference_temperaturefloat or None: The temperature (K) the model’s polarizability refers to ([model] reference_temperature_k): datasets with a temperature option are brought to it. None where no reference is declared (the atoms: their polarizability does not depend on temperature at the package’s accuracy).
retardationfloat: The coefficient c of the retardation term c omega^2 of the refractive polarizability ([model] retardation_au, atomic units, omega in hartree): added, like chi0, to refractive observations and not to electric ones or to moments. Known for helium only (TC-705); zero otherwise.
absorptionMeasuredAbsorption or None: A fixed measured-absorption term ([model] absorption = true, from data/gas/absorption/<gas>.toml, smoothed to [model] absorption_fwhm_cm if given): its Kramers-Kronig polarizability is added to every prediction and its dipole sums to the sum priors.
band_nodesint or None: [model] band_nodes (OEP 3): the infrared terms are the derived rules of every band system (<gas>_band_rules.csv), at most this many nodes each, in place of infrared_max_wavenumber’s band poles.
rotationaltuple of tuple: The rotational system’s terms, with band_nodes: a term class of its own, added to refractive observations and left out of electric ones and moments.
windowsbool: [model] windows = true: the model’s qualified intervals are the gas’s derived windows (<gas>_windows.csv), with each gap’s reason.
intervals_nmtuple of tuple of float: The qualified intervals, nm: the derived windows, or range_nm alone.
gap_reasonstuple of str: The reason of each gap between two intervals.
derived_sha256str: The SHA-256 of the derived tables the fit reads (band_nodes or windows); empty otherwise.

absorption: MeasuredAbsorption | None = None#

band_nodes: int | None = None#

chi0: float#

derived_sha256: str = ''#

description: str#

digest: str#

effective: int#

effective_min_energy: float#

fitted: tuple[DatasetOptions, ...]#

fixed: tuple[tuple[str, float, float], ...] = ()#

property fixed_terms: tuple[tuple[str, float, float], ...]#

Every term outside the fitted parameters: rotational, infrared, the rest.

Returns:

tuple of tuple: (label, strength, energy in hartree).

gap_reasons: tuple[str, ...] = ()#

gas: Gas#

infrared: tuple[tuple[str, float, float], ...] = ()#

infrared_max_wavenumber: float | None = None#

intervals_nm: tuple[tuple[float, float], ...] = ()#

lines: tuple[Line, ...]#

name: str#

range_nm: tuple[float, float]#

reference_temperature: float | None = None#

retardation: float = 0.0#

rotational: tuple[tuple[str, float, float], ...] = ()#

starts: int = 6#

sum_priors: Mapping[int, tuple[float, float]]#

validators: tuple[DatasetOptions, ...]#

windows: bool = False#

class optmat.gas.fitting.FitResult(config, model, parameters, covariance, scales=<factory>, chi2=0.0, dof=0, dataset_chi2=<factory>)[source]#

Bases: object

A fitted model with its uncertainty and statistics.

Attributes:

configFitConfig: The fit’s configuration.
modelOscillatorModel: The fitted model.
parametersnumpy.ndarray: The fitted strengths (lines, then effective) and effective energies, hartree.
covariancenumpy.ndarray: Their covariance, from (J^T J)^{-1} (not scaled by the Birge ratio).
scalesdict of str to float: The fitted scale of each dataset (1 where not fitted).
chi2float: Chi-squared of the data residuals at the solution.
dofint: Degrees of freedom: data points minus parameters.
dataset_chi2dict of str to tuple: (number of points, chi-squared) per dataset.

chi2: float = 0.0#

config: FitConfig#

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

dataset_chi2: Mapping[str, tuple[int, float]]#

dof: int = 0#

model: OscillatorModel#

parameters: Float[ndarray, 'q']#

polarizability_sigma_au(omega, *, birge=True)[source]#

Return the one-sigma uncertainty of the fitted polarizability.

Parameters:

omeganumpy.ndarray: Photon energies, hartree.
birgebool, optional: Scale the covariance by the reduced chi-squared when it exceeds one.

Returns:

numpy.ndarray: One-sigma uncertainty, atomic units.

property reduced_chi2: float#

Chi-squared per degree of freedom.

Returns:

float: chi2 / dof (dof at least 1).

scales: Mapping[str, float]#

optmat.gas.fitting.HARTREE_NM: Final = 45.56335252767#: Vacuum wavelength of a one-hartree photon, nm (2 pi c / (E_h / hbar)).

class optmat.gas.fitting.Line(label, wavelength_nm, f_prior, f_sigma)[source]#

Bases: object

A resonance line kept at its spectroscopic energy.

Attributes:

labelstr: The transition.
wavelength_nmfloat: Vacuum wavelength, nm.
f_priorfloat: Prior oscillator strength.
f_sigmafloat: Its standard uncertainty.

property energy: float#

The line’s energy.

Returns:

float: The photon energy, hartree.

f_prior: float#

f_sigma: float#

label: str#

wavelength_nm: float#

class optmat.gas.fitting.Observation(key, omega, alpha, sigma, systematic, options, orders=None, harmonic=0, partner_delta=None, model_in_numerator=False)[source]#

Bases: object

The fitted values of one dataset, as polarizabilities in atomic units.

Attributes:

keystr: source/dataset.
omeganumpy.ndarray: Photon energies, hartree.
alphanumpy.ndarray: Polarizabilities, atomic units.
sigmanumpy.ndarray: One-sigma uncertainties, atomic units.
systematicfloat or None: The dataset’s stated relative systematic uncertainty.
optionsDatasetOptions: How the dataset enters the fit.
ordersnumpy.ndarray or None: For Cauchy moments, the order k of each S(k) (then alpha holds the sums and omega is unused); None for polarizabilities.
harmonicint: For a phase-matching density ratio, the harmonic (omega is the fundamental, alpha holds the ratios); 0 otherwise.
partner_deltanumpy.ndarray or None: For a ratio, the partner gas’s alpha(h omega) - alpha(omega) from its fixed model, atomic units.
model_in_numeratorbool: For a ratio, True if the fitted gas’s difference is the ratio’s numerator (rho_partner / rho_fitted), False if its denominator.

alpha: Float[ndarray, 'n']#

harmonic: int = 0#

key: str#

model_in_numerator: bool = False#

omega: Float[ndarray, 'n']#

options: DatasetOptions#

orders: Float[ndarray, 'n'] | None = None#

partner_delta: Float[ndarray, 'n'] | None = None#

sigma: Float[ndarray, 'n']#

systematic: float | None#

optmat.gas.fitting.dumps(result)[source]#

Serialise a fit result as JSON text.

Parameters:

resultFitResult: The result.

Returns:

str: Indented JSON.

optmat.gas.fitting.fit(config, data=None, *, starts=None, start=None)[source]#

Fit a configuration’s model to its data.

Several starting points spread the effective oscillators over different energies; the solution with the lowest cost is kept.

Parameters:

configFitConfig: The fit.
datasequence of Observation, optional: The observations; by default those the configuration names (observations()).
startsint, optional: The number of spread starting points; by default the configuration’s.
startFitResult, optional: A previous fit of the same model (for instance on more data), whose solution is tried first; with starts=0 the fit follows it to the nearest minimum.

Returns:

FitResult: The fitted model, its covariance and statistics.

Raises:

ValueError: If there is no starting point, or start has a different model layout.

optmat.gas.fitting.load_config(name)[source]#

Load a fit configuration.

Parameters:

namestr or pathlib.Path: The configuration’s name (data/gas/fits/<name>.toml) or path.

Returns:

FitConfig: The configuration.

Raises:

DataError: If the configuration is malformed or names an unknown dataset.

optmat.gas.fitting.observations(config)[source]#

Return the fitted observations of a configuration.

Parameters:

configFitConfig: The fit.

Returns:

tuple of Observation: One per fitted dataset.

optmat.gas.fitting.result_record(result)[source]#

Return a fit result as a JSON-serialisable record.

Parameters:

resultFitResult: The result.

Returns:

dict: The model’s terms, covariance, statistics and provenance.

optmat.gas.fitting.validation(result)[source]#

Compare the fit with its validator datasets.

Parameters:

resultFitResult: The fit.

Returns:

dict: Per validator: the number of values, their chi-squared against the fit (where uncertainties are stated) and their mean relative deviation from it; or a note when the dataset’s quantity has no comparison yet. A validator may take a wavelength window (range_nm); one that is also fitted, in another window, is compared at its fitted scale.