solprop.physdata.selection#

Name the material models a run takes from optmat, and record the ones it resolved.

A MaterialSelection is the small immutable choice a caller makes: which linear, electronic, Raman and ionisation models, at which carrier, under which approximation policies. "recommended" is optmat’s recommended model of each material; a model name selects another one from optmat’s registry, and an optmat model object is taken as it is. The selection holds names and policies, never data: the models are resolved where a species or a solid is built.

A MaterialRecord is what a resolved model leaves behind: optmat’s identity of it (name, quantity, material, content digest and status) in plain values, ready for a run’s manifest. Every optmat-backed object solprop builds exposes its records as material_records.

A MaterialManifest is a run’s whole material record: the optmat version, every resolved model’s record, the species, compositions and solids with their axes, the policies in force and what was measured about them. Its identities and policies enter the run’s resume key (output schema 8); see Output: what a run leaves behind.

This module imports nothing from optmat, so building a selection costs nothing; see Materials: gases, metals and glasses for the models, their statuses and the warnings they raise.

Module Attributes

`STATUSES`	optmat's statuses, from most to least curated; `user` marks a caller's model.
`ELECTRONIC_POLICIES`	The electronic-response policies.
`DISPERSIVE_POLICIES`	The dispersive electronic policies and the evaluator each selects (SEP 6).
`ENERGY_LOSS_POLICIES`	The plasma energy-loss conventions: the rate-weighted energy at the peak field.
`RAMAN_POLICIES`	The names `MaterialSelection.raman` takes, for a gas and for silica alike.
`RAMAN_SHIFT_POLICIES`	The density-shift approximations a Raman response may take; `None` takes none.
`ModelChoice`	A model choice: `"recommended"`, an optmat model name, or an optmat model object (anything with an `identity`, an `OptmatModel`), checked when resolved.

Classes

`DiluteScalingCheck`(label, material, density, ...)	Record the error of linear density scaling for one gas at its largest density.
`MaterialLog`([seen, ranges, dropped])	Keep what one evaluation context has warned about and found out of range.
`MaterialManifest`([optmat_version, ...])	Record the optmat materials of one run: identities, policies and measurements.
`MaterialRecord`(name, kind, material, digest, ...)	Record one resolved optmat model by its identity, in plain values.
`MaterialSelection`([linear, electronic, ...])	Choose the optmat models and approximation policies for a run's materials.
`ModelIdentityLike`(args, *kwargs)	Read the fields of an optmat `ModelIdentity` that a record keeps.
`OptmatModel`(args, *kwargs)	Anything that carries an optmat identity: a model, a response or a bundle.

solprop.physdata.selection.DISPERSIVE_POLICIES: Final[Mapping[str, str]] = {'gas-polynomial': 'polynomial', 'symmetric-kerr': 'symmetric'}#: The dispersive electronic policies and the evaluator each selects (SEP 6).

class solprop.physdata.selection.DiluteScalingCheck(label, material, density, temperature, wavelength, relative_error, threshold, reason='')[source]#

Bases: object

Record the error of linear density scaling for one gas at its largest density.

solprop forms a gas’s susceptibility as N alpha / eps0, the dilute limit of optmat’s Lorentz–Lorenz law with its refractivity virial. This is the relative difference of the two in n - 1 at the density where it is largest.

Attributes:

labelstr: The population, or the gas, it was evaluated for.
materialstr: The gas.
densityfloat: The largest number density of the population, m^-3.
temperaturefloat: Temperature in K at that density.
wavelengthfloat: Vacuum wavelength in m at which the error is largest over the band.
relative_errorfloat: (n - 1)_dilute / (n - 1)_optmat - 1, dimensionless; negative where the dilute law is low. NaN when the check could not be measured.
thresholdfloat: The bound above which a warning is raised, relative.
reasonstr: Empty for a measured check; otherwise why optmat could not evaluate it. An unmeasured check never fails the fill it belongs to.

Examples

>>> from solprop.physdata.selection import DiluteScalingCheck
>>> check = DiluteScalingCheck("Ar", "Ar", 1.5e27, 293.15, 8e-7, -1.2e-2, 1e-2)
>>> check.exceeded
True

density: float#

property exceeded: bool[source]#

Return whether the error’s magnitude is above the threshold.

Returns:

bool: abs(relative_error) > threshold for a measured check; False for one that was not measured.

label: str#

material: str#

property measured: bool[source]#

Return whether the error was measured.

Returns:

bool: True unless optmat refused the evaluation (see reason).

reason: str = ''#

relative_error: float#

temperature: float#

threshold: float#

to_dict()[source]#

Return the check as plain values, for a run’s record.

Returns:

collections.abc.Mapping: Every field; relative_error and wavelength are None for a check that was not measured.

wavelength: float#

solprop.physdata.selection.ELECTRONIC_POLICIES: Final[tuple[str, ...]] = ('recommended', 'carrier-kerr', 'symmetric-kerr', 'gas-polynomial')#

The electronic-response policies.

"recommended" and "carrier-kerr" name the Kerr coefficient at the carrier, one number per species and run (SEP 3, section 4.3). The two dispersive policies of SEP 6 evaluate optmat’s whole hyperpolarizability model at the absolute frequencies of every quartet the cubic couples (DISPERSIVE_POLICIES names their evaluators): "symmetric-kerr" factorises the Kerr diagonal symmetrically over the four legs, and "gas-polynomial" evaluates the gas dispersion polynomial itself.

solprop.physdata.selection.ENERGY_LOSS_POLICIES: Final[tuple[str, ...]] = ('peak-weighted',)#: The plasma energy-loss conventions: the rate-weighted energy at the peak field.

class solprop.physdata.selection.MaterialLog(seen=<factory>, ranges=<factory>, dropped=<factory>)[source]#

Bases: object

Keep what one evaluation context has warned about and found out of range.

A run keeps one from its construction to its record, so that each material warning is raised once per run (solprop.physdata._optmat.material_context), and its manifest records the bands it found outside a model’s intervals.

Attributes:

seenset of tuple of str: The keys of the warnings already raised.
rangesdict: For each model evaluated outside its qualified intervals, keyed by its digest: the material, the model’s name and the set of phrases naming the parts of the bands outside them.
droppeddict: For each transparent solid index evaluated in the context, keyed by its model’s digest and its absorption bound in 1/m: the largest extinction coefficient it dropped, the largest absorption coefficient in 1/m and that absorption’s vacuum wavelength in m. The run’s own, whatever the adapter dropped in other runs (SEP 3, Q28).

copy()[source]#

Return an independent log holding what this one holds so far.

Returns:

MaterialLog: The same warning keys and out-of-interval bands, in new containers.

Examples

>>> from solprop.physdata.selection import MaterialLog
>>> parent = MaterialLog()
>>> parent.seen.add(("range", "x"))
>>> child = parent.copy()
>>> child.seen.add(("range", "y"))
>>> sorted(parent.seen), sorted(child.seen)
([('range', 'x')], [('range', 'x'), ('range', 'y')])

dropped: dict[tuple[str, float], tuple[float, float, float]]#

range_entries()[source]#

Return the out-of-interval record, in a canonical order.

Returns:

tuple of dict: One entry per model: material, model, digest and the sorted outside phrases; sorted by material, model and digest.

ranges: dict[str, tuple[str, str, set[str]]]#

record_dropped(key, extinction, absorption, wavelength)[source]#

Add the loss a transparent index dropped in one evaluation.

Parameters:

keytuple: The model’s digest and the absorption bound in 1/m.
extinctionfloat: The largest k the evaluation dropped, dimensionless.
absorptionfloat: The largest 4 pi k / lambda it dropped, 1/m.
wavelengthfloat: The vacuum wavelength in m of that absorption, or NaN.

Examples

>>> from solprop.physdata.selection import MaterialLog
>>> log = MaterialLog()
>>> log.record_dropped(("digest", 100.0), 1e-9, 2.0, 6e-6)
>>> log.record_dropped(("digest", 100.0), 1e-8, 1.0, 1e-5)
>>> log.dropped[("digest", 100.0)]
(1e-08, 2.0, 6e-06)

record_range(digest, material, name, parts)[source]#

Add the parts of a band a model was evaluated at outside its intervals.

Parameters:

digeststr: The model’s digest.
materialstr: The material it serves.
namestr: The model’s name.
partssequence of str: The phrases naming the parts of the band outside the model’s intervals; none when the band is not known.

seen: set[tuple[str, ...]]#

class solprop.physdata.selection.MaterialManifest(optmat_version='', selection=None, records=(), species=(), compositions=(), solids=(), policies=None, dilute_scaling=(), ranges=(), citations=(), electronic=(), peak_fields=(), raman=())[source]#

Bases: object

Record the optmat materials of one run: identities, policies and measurements.

Built once per run from its mixtures, modes and solids (solprop.driver.material_output.material_manifest()) and stored in its RunMetadata. A run with no optmat-backed object and no selection has the empty manifest, MaterialManifest().

Two parts are distinguished. The identities and policies – the optmat version, every model’s record, the species, compositions and solids, and the policies – are what was computed, and enter the resume key (hashed()). The measurements – the dilute-scaling errors, the loss a transparent solid dropped, the bands outside the models’ qualified intervals, the citations of the other material objects and the carrier Kerr coefficients with their third-harmonic discrepancy – say how good the approximations were, and are recorded beside it. The selection is recorded as it was given; what it resolved to is in the records, so naming a model "recommended" or by its name hashes alike.

Attributes:

optmat_versionstr: The installed optmat’s full version string; empty for an empty manifest.
selectioncollections.abc.Mapping or None: MaterialSelection.to_dict() of the run’s selection, or None.
recordstuple of MaterialRecord: Every resolved model, each digest once, sorted by material, kind, name and digest.
speciestuple of collections.abc.Mapping: One entry per optmat-backed population: label, species and the digests of its records.
compositionstuple of collections.abc.Mapping: The named optmat compositions a mixture was built from: name, labels and fractions.
solidstuple of collections.abc.Mapping: One entry per optmat solid: material, axis (empty for an isotropic one), model, digest, transparent, absorption_bound (1/m, for a transparent one) and the transparency measured in the run itself (solprop.physdata.glasses.OptmatGlass.run_transparency()).
policiescollections.abc.Mapping: The approximation policies in force: linear_density_scaling (the gas law and its warning threshold), electronic and carrier_wavelength as selected, electronic_response (the carrier-kerr law and the carrier it was evaluated at, when an optmat Kerr model is in the run; or a dispersive law, its evaluator, harmonic sector, tensor approximation, and each species’ support-record digest and regions, when the run’s electronic response is SEP 6’s dispersive one), gnlse_raman (a GNLSE run’s held-back fraction, where it came from and the silica bundle), raman_shift and raman_reference_temperature, energy_loss, and ionisation: one entry per optmat rate, with its threshold kind, its reference field, its constant energy per event and that energy’s bound (solprop.nonlinear.optmat_rates.OptmatRate.manifest_entry()). A policy a later phase resolves is recorded as selected, or None.
dilute_scalingtuple of collections.abc.Mapping: DiluteScalingCheck.to_dict() of each optmat population, measured once per run over the run’s band.
rangestuple of collections.abc.Mapping: For each model evaluated outside its qualified intervals: material, model, digest and the outside phrases its range warning named.
citationstuple of collections.abc.Mapping: The other material objects of the run (supplied or solprop’s own): object (the class), name and citation.
electronictuple of collections.abc.Mapping: Each optmat population’s Kerr coefficient at the carrier, beside optmat’s third-harmonic one and their ratio where that is within optmat’s fitted data (solprop.physdata.nonlinear_data.CarrierKerr.to_dict(), with the label): what the single-coefficient carrier-kerr approximation leaves out. Under a dispersive policy, each species’ dispersive model instead: its evaluator and sector, model and support digests, leg bound, band edges and the regions of the run’s active band (solprop.physdata.nonlinear_data.ElectronicRegions.to_dict()).
peak_fieldstuple of collections.abc.Mapping: The post-run diagnostic of each optmat ionisation rate: the largest field its population saw at the save planes, against the model’s maximum field, and the rate-weighted energy there against the constant the loss paid (solprop.nonlinear.optmat_rates.PeakFieldReport). Recorded once the run has run; empty before.
ramantuple of collections.abc.Mapping: For each optmat Raman response: its labels, composition, reference temperature, pump wavelength, group and term counts, the densities declared to its range check, the composition’s spread along the run, and a held line shift with its phase bound over the run’s window (SEP 3, section 4.4).

Examples

>>> from solprop.physdata.selection import MaterialManifest
>>> MaterialManifest().empty, MaterialManifest().hashed() is None
(True, True)

citations: tuple[Mapping[str, object], ...] = ()#

compositions: tuple[Mapping[str, object], ...] = ()#

dilute_scaling: tuple[Mapping[str, object], ...] = ()#

electronic: tuple[Mapping[str, object], ...] = ()#

property empty: bool[source]#

Return whether the run took nothing from optmat and selected nothing.

Returns:

bool: True for a run of solprop’s own materials only.

classmethod from_dict(document)[source]#

Rebuild a manifest from to_dict().

Parameters:

documentcollections.abc.Mapping or None: A stored manifest, or None for the empty one.

Returns:

MaterialManifest: The manifest, hashing as the one that was stored.

Raises:

MaterialError: If a stored record is malformed.

Examples

>>> from solprop.physdata.selection import MaterialManifest, MaterialSelection
>>> selection = MaterialSelection().to_dict()
>>> manifest = MaterialManifest("0.1.1", selection, policies={})
>>> MaterialManifest.from_dict(manifest.to_dict()) == manifest
True

hashed()[source]#

Return the identities and policies, which the resume key covers.

Returns:

dict or None: The optmat version, the records by material:kind:name, the species by label, the compositions, the solids’ identities and policies, and the policies; None for an empty manifest.

Examples

>>> from solprop.physdata.selection import MaterialManifest, MaterialSelection
>>> selection = MaterialSelection().to_dict()
>>> manifest = MaterialManifest("0.1.1", selection, policies={})
>>> sorted(manifest.hashed())[:3]
['compositions', 'optmat_version', 'policies']

optmat_version: str = ''#

peak_fields: tuple[Mapping[str, object], ...] = ()#

policies: Mapping[str, object] | None = None#

raman: tuple[Mapping[str, object], ...] = ()#

ranges: tuple[Mapping[str, object], ...] = ()#

records: tuple[MaterialRecord, ...] = ()#

selection: Mapping[str, object] | None = None#

solids: tuple[Mapping[str, object], ...] = ()#

species: tuple[Mapping[str, object], ...] = ()#

to_dict()[source]#

Return the whole manifest as plain values, for a file.

Returns:

dict or None: hashed(), with the selection, the solids’ measurements, the dilute-scaling checks, the out-of-interval bands, the citations, the carrier Kerr coefficients, the post-run peak fields and the Raman responses’ assemblies; None for an empty manifest.

class solprop.physdata.selection.MaterialRecord(name, kind, material, digest, status, status_reason, optmat_version, modified=(), base='', sources=(), reference_temperature=None)[source]#

Bases: object

Record one resolved optmat model by its identity, in plain values.

Attributes:

namestr: optmat’s model name, such as "fit/Ar" or "eos/Ar".
kindstr: The quantity the model gives ("gas_refractive", "equation_of_state", "transport", "solid", …).
materialstr: The gas, solid or composition the model describes.
digeststr: The SHA-256 of the model’s canonical record, 64 hexadecimal digits: what identifies its numbers.
statusstr: One of STATUSES.
status_reasonstr: Why the status is what it is, where the source says.
optmat_versionstr: The optmat version that built the model; informational, not part of the digest.
modifiedtuple of tuple of str: The overrides applied, (name, value) sorted by name; empty for a curated model.
basestr: The digest of the curated model an override started from, or empty.
sourcestuple of str: The source records the model rests on, as optmat names them.
reference_temperaturefloat or None: The temperature in K a gas polarizability refers to, where its source declares one.

Raises:

MaterialError: If the digest is not 64 hexadecimal digits or the status is unknown.

base: str = ''#

digest: str#

classmethod from_identity(identity)[source]#

Build a record from an optmat ModelIdentity.

Parameters:

identityoptmat.identity.ModelIdentity: The identity of a resolved model.

Returns:

MaterialRecord: Its name, kind, material, digest, status and override fields.

kind: str#

material: str#

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

name: str#

optmat_version: str#

reference_temperature: float | None = None#

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

status: str#

status_reason: str#

to_dict()[source]#

Return the record as canonical plain values.

Returns:

dict: Every field; modified as a list of [name, value] pairs and sources as a list.

class solprop.physdata.selection.MaterialSelection(linear='recommended', electronic='recommended', raman='recommended', ionisation='recommended', carrier_wavelength=None, energy_loss='peak-weighted', raman_shift=None)[source]#

Bases: object

Choose the optmat models and approximation policies for a run’s materials.

Each model field takes "recommended" (optmat’s recommended model of the material), an optmat model name, or an optmat model object, such as one made by with_parameters. A name or an object is checked against the material it is used for when it is resolved, never matched to another material by name. MaterialSelection() is what an omitted selection means everywhere.

Attributes:

linearstr or OptmatModel: The linear dispersion model of a gas: its per-particle polarizability, used at linear density scaling. The family also covers what a driver resolves beside it: the gas’s equation of state and transport, the composition of air, and the default wall or slab cladding (fused silica).
electronicstr: The electronic third-order policy (ELECTRONIC_POLICIES): "recommended" or "carrier-kerr", both the Kerr coefficient evaluated at the carrier; or a dispersive policy of SEP 6, "symmetric-kerr" or "gas-polynomial", which evaluates optmat’s hyperpolarizability model at every quartet’s absolute frequencies (DispersiveKerrResponse).
ramanstr or OptmatModel: The Raman response (RAMAN_POLICIES): "recommended", the curated default of a gas fill and of fused silica alike; "provisional", which also admits a gas’s provisional bands with a warning and is refused for silica; on a gas run an optmat response object, and on a silica run an optmat bundle name or object, each refused in the other context. The family covers the silica bundle of a GNLSE run (its f_R) and of a guide’s tensor response.
ionisationstr or OptmatModel: The ionisation rate model: "recommended", a literature form such as "ppt_ilkov", or a rate-model object.
carrier_wavelengthfloat or None: Vacuum carrier wavelength in m at which the carrier electronic coefficient, the Raman pump dispersion and the rate are evaluated; positive and finite, or None to take the run’s grid reference. A dispersive electronic policy does not use it: its response is evaluated at absolute frequencies.
energy_lossstr: The plasma energy-loss convention; "peak-weighted" is the only one, the rate-weighted energy per event at the run’s peak field.
raman_shiftstr or None: None, or "reference-density": the explicit approximation that holds a density-dependent Raman line shift at a reference density.

Raises:

MaterialError: If a field is of the wrong type, empty, or not one of its policies.

Examples

>>> from solprop.physdata.selection import MaterialSelection
>>> selection = MaterialSelection(carrier_wavelength=800e-9)
>>> selection.linear, selection.energy_loss
('recommended', 'peak-weighted')
>>> MaterialSelection(energy_loss="mean")
Traceback (most recent call last):
    ...
solprop.exceptions.MaterialError: MaterialSelection.energy_loss must be one of ...

carrier_wavelength: float | None = None#

electronic: str = 'recommended'#

energy_loss: str = 'peak-weighted'#

ionisation: ModelChoice = 'recommended'#

linear: ModelChoice = 'recommended'#

raman: ModelChoice = 'recommended'#

raman_shift: str | None = None#

to_dict()[source]#

Return the selection as plain values, for a run’s record.

Returns:

dict: Every field; a model object enters as its identity record.

Examples

>>> from solprop.physdata.selection import MaterialSelection
>>> MaterialSelection().to_dict()["carrier_wavelength"] is None
True

type solprop.physdata.selection.ModelChoice = str | object#: A model choice: "recommended", an optmat model name, or an optmat model object (anything with an identity, an OptmatModel), checked when resolved.

class solprop.physdata.selection.ModelIdentityLike(*args, **kwargs)[source]#

Bases: Protocol

Read the fields of an optmat ModelIdentity that a record keeps.

property base: str[source]#: Return the digest of the curated model an override started from.

property digest: str[source]#: Return the SHA-256 of its canonical record.

property kind: str[source]#: Return the quantity the model gives.

property material: str[source]#: Return the material it describes.

property modified: tuple[tuple[str, str], ...][source]#: Return the overrides applied.

property name: str[source]#: Return the model’s name.

property optmat_version: str[source]#: Return the optmat version that built it.

property reference_temperature: float | None[source]#: Return the temperature in K a gas polarizability refers to, if declared.

property sources: tuple[str, ...][source]#: Return the source records the model rests on.

property status: str[source]#: Return its status.

property status_reason: str[source]#: Return why its status is what it is.

class solprop.physdata.selection.OptmatModel(*args, **kwargs)[source]#

Bases: Protocol

Anything that carries an optmat identity: a model, a response or a bundle.

property identity: ModelIdentityLike[source]#: Return the model’s optmat ModelIdentity.

solprop.physdata.selection.RAMAN_POLICIES: Final[tuple[str, ...]] = ('recommended', 'provisional')#

The names MaterialSelection.raman takes, for a gas and for silica alike.

"recommended" is the curated default in both contexts: optmat’s response of a gas fill (SEP 3, section 4.4), and optmat’s default silica bundle on a fibre’s GNLSE, or its tensor bundle for a vector run (section 4.5). "provisional" is a gas policy: it also admits optmat’s provisional bands (N2O’s, D13), and a silica run refuses it by name. Beside these, a gas run takes an optmat response object and a silica run a bundle name or object; each refuses the other’s, by name.

solprop.physdata.selection.RAMAN_SHIFT_POLICIES: Final[tuple[str | None, ...]] = (None, 'reference-density')#: The density-shift approximations a Raman response may take; None takes none.

solprop.physdata.selection.STATUSES: Final[tuple[str, ...]] = ('validated', 'provisional', 'untested', 'comparison', 'user')#: optmat’s statuses, from most to least curated; user marks a caller’s model.