solprop.physdata.selection#
Name the material models a run takes from optmat, and record the ones it resolved.
MaterialSelectionis the small immutable choice a caller makes: which linear, electronic, Raman and ionisation models, at which carrier, under which approximation policies (STATUSES,ELECTRONIC_POLICIES,RAMAN_POLICIES, …). It holds names and policies, never data: models are resolved where a species or solid is built.MaterialRecordis what a resolved model leaves behind, optmat’s identity of it in plain values; every optmat-backed object exposes its records asmaterial_records.OptmatModelandModelIdentityLikeare the protocols it reads.MaterialManifestis a run’s whole material record (the optmat version, the records, species, compositions, solids, policies and measurements such as eachDiluteScalingCheck), whose identities and policies enter the run’s resume key;hashed_document()is its hashed part.MaterialLogcollects what one evaluation context warned about.
This module imports nothing from optmat, so building a selection costs nothing. See Selecting and inspecting material data for the choices and Recording and inspecting provenance for the manifest.
Module Attributes
optmat's statuses, from most to least curated; |
|
The electronic-response policies. |
|
The dispersive electronic policies and the evaluator each selects (SEP 6). |
|
The plasma energy-loss conventions: the rate-weighted energy at the peak field. |
|
The names |
|
The density-shift approximations a Raman response may take; |
|
A model choice: |
Functions
|
Return the hashed part of a stored manifest, as the stored text holds it. |
Classes
|
Record the error of linear density scaling for one gas at its largest density. |
|
Keep what one evaluation context has warned about and found out of range. |
|
Record the optmat materials of one run: identities, policies and measurements. |
|
Record one resolved optmat model by its identity, in plain values. |
|
Choose the optmat models and approximation policies for a run's materials. |
|
Read the fields of an optmat |
|
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:
objectRecord 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 inn - 1at 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
- property exceeded: bool[source]#
Whether the error’s magnitude is above the threshold.
abs(relative_error) > thresholdfor a measured check; False for one that was not measured.
- property measured: bool[source]#
Whether the error was measured.
True unless optmat refused the evaluation (see reason).
- 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_POLICIESnames 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:
objectKeep 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')])
- range_entries()[source]#
Return the out-of-interval record, in a canonical order.
- Returns:
- tuple of dict
One entry per model:
material,model,digestand the sortedoutsidephrases; sorted by material, model and digest.
- 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
kthe evaluation dropped, dimensionless.- absorptionfloat
The largest
4 pi k / lambdait 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.
- 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:
objectRecord 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 itsRunMetadata. 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, orNone.- 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,speciesand the digests of itsrecords.- compositionstuple of collections.abc.Mapping
The named optmat compositions a mixture was built from:
name,labelsandfractions.- 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 thetransparencymeasured 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),electronicandcarrier_wavelengthas selected,electronic_response(thecarrier-kerrlaw 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_shiftandraman_reference_temperature,energy_loss, andionisation: 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, orNone.- 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,digestand theoutsidephrases its range warning named.- citationstuple of collections.abc.Mapping
The other material objects of the run (supplied or solprop’s own):
object(the class),nameandcitation.- 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 thelabel): what the single-coefficientcarrier-kerrapproximation 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)
- property empty: bool[source]#
Whether the run took nothing from optmat and selected nothing.
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
Nonefor 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;Nonefor 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']
- records: tuple[MaterialRecord, ...] = ()#
- 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;Nonefor 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:
objectRecord 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.
- 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:
objectChoose 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 bywith_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 (itsf_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
Noneto 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 ...
- ionisation: ModelChoice = 'recommended'#
- linear: ModelChoice = 'recommended'#
- raman: ModelChoice = 'recommended'#
- type solprop.physdata.selection.ModelChoice = str | object#
A model choice:
"recommended", an optmat model name, or an optmat model object (anything with anidentity, anOptmatModel), checked when resolved.
- class solprop.physdata.selection.ModelIdentityLike(*args, **kwargs)[source]#
Bases:
ProtocolRead the fields of an optmat
ModelIdentitythat a record keeps.- property modified: tuple[tuple[str, str], ...][source]#
The overrides applied,
(name, value)sorted by name.
- class solprop.physdata.selection.OptmatModel(*args, **kwargs)[source]#
Bases:
ProtocolAnything that carries an optmat identity: a model, a response or a bundle.
- property identity: ModelIdentityLike[source]#
The model’s optmat
ModelIdentity.
- solprop.physdata.selection.RAMAN_POLICIES: Final[tuple[str, ...]] = ('recommended', 'provisional')#
The names
MaterialSelection.ramantakes, 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;
Nonetakes none.
- solprop.physdata.selection.STATUSES: Final[tuple[str, ...]] = ('validated', 'provisional', 'untested', 'comparison', 'user')#
optmat’s statuses, from most to least curated;
usermarks a caller’s model.
- solprop.physdata.selection.hashed_document(document)[source]#
Return the hashed part of a stored manifest, as the stored text holds it.
MaterialManifest.hashed()of the manifestMaterialManifest.to_dict()wrote, taken from the stored document without rebuilding its records, so that a record written by another build of the same output schema hashes as it was written.- Parameters:
- documentcollections.abc.Mapping or None
A stored manifest, or
Nonefor the empty one.
- Returns:
- dict or None
The optmat version, records, species, compositions, solids’ identities and policies;
Nonefor the empty manifest.
Examples
>>> from solprop.physdata.selection import ( ... MaterialManifest, MaterialSelection, hashed_document, ... ) >>> manifest = MaterialManifest("0.1.1", MaterialSelection().to_dict(), policies={}) >>> hashed_document(manifest.to_dict()) == manifest.hashed() True