Source code for solprop.physdata.selection

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

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

- :class:`MaterialSelection` is 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.
- :class:`MaterialRecord` is what a resolved model leaves behind, optmat's identity of
  it in plain values; every optmat-backed object exposes its records as
  ``material_records``. :class:`OptmatModel` and :class:`ModelIdentityLike` are the
  protocols it reads.
- :class:`MaterialManifest` is a run's whole material record (the optmat version, the
  records, species, compositions, solids, policies and measurements such as each
  :class:`DiluteScalingCheck`), whose identities and policies enter the run's resume
  key; :func:`hashed_document` is its hashed part. :class:`MaterialLog` collects what
  one evaluation context warned about.

This module imports nothing from optmat, so building a selection costs nothing. See
:doc:`/guide/media/material-selection` for the choices and
:doc:`/guide/results/provenance` for the manifest.
"""

import math
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass, field
from typing import Final, Protocol, cast, runtime_checkable

import numpy as np

from solprop._identity import canonical_json
from solprop.exceptions import MaterialError

__all__ = [
    "DISPERSIVE_POLICIES",
    "ELECTRONIC_POLICIES",
    "RAMAN_POLICIES",
    "RAMAN_SHIFT_POLICIES",
    "STATUSES",
    "DiluteScalingCheck",
    "MaterialLog",
    "MaterialManifest",
    "MaterialRecord",
    "MaterialSelection",
    "ModelChoice",
    "ModelIdentityLike",
    "OptmatModel",
    "hashed_document",
]

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

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 (:data:`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.
"""

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

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.
"""

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


[docs] @runtime_checkable class ModelIdentityLike(Protocol): """Read the fields of an optmat ``ModelIdentity`` that a record keeps."""
[docs] @property def name(self) -> str: # numpydoc ignore=RT01 """The model's name.""" ...
[docs] @property def kind(self) -> str: # numpydoc ignore=RT01 """Quantity the model gives.""" ...
[docs] @property def material(self) -> str: # numpydoc ignore=RT01 """Material it describes.""" ...
[docs] @property def digest(self) -> str: # numpydoc ignore=RT01 """SHA-256 of its canonical record.""" ...
[docs] @property def optmat_version(self) -> str: # numpydoc ignore=RT01 """Version of optmat that built it.""" ...
[docs] @property def status(self) -> str: # numpydoc ignore=RT01 """The status, one of :data:`STATUSES`.""" ...
[docs] @property def status_reason(self) -> str: # numpydoc ignore=RT01 """Why its status is what it is.""" ...
[docs] @property def modified(self) -> tuple[tuple[str, str], ...]: # numpydoc ignore=RT01 """The overrides applied, ``(name, value)`` sorted by name.""" ...
[docs] @property def base(self) -> str: # numpydoc ignore=RT01 """Digest of the curated model an override started from.""" ...
[docs] @property def sources(self) -> tuple[str, ...]: # numpydoc ignore=RT01 """Source records the model rests on.""" ...
[docs] @property def reference_temperature(self) -> float | None: # numpydoc ignore=RT01 """Temperature in K a gas polarizability refers to, if declared.""" ...
[docs] @runtime_checkable class OptmatModel(Protocol): """Anything that carries an optmat identity: a model, a response or a bundle."""
[docs] @property def identity(self) -> ModelIdentityLike: # numpydoc ignore=RT01 """The model's optmat ``ModelIdentity``.""" ...
# A type checker cannot match optmat's models to `OptmatModel`: their `identity` is a # `functools.cached_property`, which static protocol matching does not see through. The # choice is therefore typed as any object and checked at run time, where `isinstance` # against the protocol works. type ModelChoice = str | object """A model choice: ``"recommended"``, an optmat model name, or an optmat model object (anything with an ``identity``, an :class:`OptmatModel`), checked when resolved.""" def _choice(value: object, field: str) -> ModelChoice: """Validate one model choice: a non-empty name or an optmat model object.""" if isinstance(value, str): name = value.strip() if not name: msg = f"MaterialSelection.{field} must name a model, got an empty string" raise MaterialError(msg) return name if isinstance(value, OptmatModel): return value msg = ( f"MaterialSelection.{field} must be 'recommended', an optmat model name or an " f"optmat model object, got {type(value).__name__}" ) raise MaterialError(msg) def _choice_record(value: ModelChoice) -> str | dict[str, object]: """Return a choice as plain values: its name, or a model object's record.""" if isinstance(value, str): return value return MaterialRecord.from_identity(cast("OptmatModel", value).identity).to_dict()
[docs] @dataclass(frozen=True) class MaterialSelection: """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 ---------- linear : str 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). electronic : str The electronic third-order policy (:data:`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 (:class:`~solprop.nonlinear.responses.DispersiveKerrResponse`). raman : str or OptmatModel The Raman response (:data:`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. ionisation : str or OptmatModel The ionisation rate model: ``"recommended"``, a literature form such as ``"ppt_ilkov"``, or a rate-model object. carrier_wavelength : float 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. raman_shift : str 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.carrier_wavelength ('recommended', 8e-07) >>> MaterialSelection(electronic="mean") # doctest: +ELLIPSIS Traceback (most recent call last): ... solprop.exceptions.MaterialError: MaterialSelection.electronic must be one of ... """ linear: ModelChoice = "recommended" electronic: str = "recommended" raman: ModelChoice = "recommended" ionisation: ModelChoice = "recommended" carrier_wavelength: float | None = None raman_shift: str | None = None def __post_init__(self) -> None: """Validate every field without resolving any model.""" for name in ("linear", "raman", "ionisation"): object.__setattr__(self, name, _choice(getattr(self, name), name)) policies: tuple[tuple[str, object, tuple[str | None, ...]], ...] = ( ("electronic", self.electronic, ELECTRONIC_POLICIES), ("raman_shift", self.raman_shift, RAMAN_SHIFT_POLICIES), ) for name, value, allowed in policies: if value not in allowed: msg = ( f"MaterialSelection.{name} must be one of {allowed}, got {value!r}" ) raise MaterialError(msg) carrier = self.carrier_wavelength if carrier is not None and ( isinstance(carrier, bool) or not isinstance(carrier, (int, float)) or not math.isfinite(carrier) or carrier <= 0 ): msg = ( "MaterialSelection.carrier_wavelength must be a positive finite " f"wavelength in m or None, got {carrier!r}" ) raise MaterialError(msg)
[docs] def to_dict(self) -> dict[str, object]: """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 """ return { "linear": _choice_record(self.linear), "electronic": self.electronic, "raman": _choice_record(self.raman), "ionisation": _choice_record(self.ionisation), "carrier_wavelength": self.carrier_wavelength, "raman_shift": self.raman_shift, }
[docs] @dataclass(frozen=True) class MaterialRecord: """Record one resolved optmat model by its identity, in plain values. Attributes ---------- name : str optmat's model name, such as ``"fit/Ar"`` or ``"eos/Ar"``. kind : str The quantity the model gives (``"gas_refractive"``, ``"equation_of_state"``, ``"transport"``, ``"solid"``, ...). material : str The gas, solid or composition the model describes. digest : str The SHA-256 of the model's canonical record, 64 hexadecimal digits: what identifies its numbers. status : str One of :data:`STATUSES`. status_reason : str Why the status is what it is, where the source says. optmat_version : str The optmat version that built the model; informational, not part of the digest. modified : tuple of tuple of str The overrides applied, ``(name, value)`` sorted by name; empty for a curated model. base : str The digest of the curated model an override started from, or empty. sources : tuple of str The source records the model rests on, as optmat names them. reference_temperature : float 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. """ name: str kind: str material: str digest: str status: str status_reason: str optmat_version: str modified: tuple[tuple[str, str], ...] = () base: str = "" sources: tuple[str, ...] = () reference_temperature: float | None = None def __post_init__(self) -> None: """Validate the digest and the status.""" if len(self.digest) != 64 or any( c not in "0123456789abcdef" for c in self.digest ): msg = f"{self.name}: a digest is 64 hexadecimal digits, got {self.digest!r}" raise MaterialError(msg) if self.status not in STATUSES: msg = f"{self.name}: status {self.status!r} is not one of {STATUSES}" raise MaterialError(msg) object.__setattr__( self, "modified", tuple((str(k), str(v)) for k, v in self.modified) ) object.__setattr__(self, "sources", tuple(str(v) for v in self.sources))
[docs] @classmethod def from_identity(cls, identity: ModelIdentityLike) -> "MaterialRecord": """Build a record from an optmat ``ModelIdentity``. Parameters ---------- identity : optmat.identity.ModelIdentity The identity of a resolved model. Returns ------- MaterialRecord Its name, kind, material, digest, status and override fields; the status reason without optmat's internal tracker ids. """ # _optmat imports this module: the import waits for the call. from solprop.physdata._optmat import optmat_text # noqa: PLC0415 return cls( name=identity.name, kind=identity.kind, material=identity.material, digest=identity.digest, status=identity.status, status_reason=optmat_text(identity.status_reason), optmat_version=identity.optmat_version, modified=identity.modified, base=identity.base, sources=identity.sources, reference_temperature=identity.reference_temperature, )
[docs] def to_dict(self) -> dict[str, object]: """Return the record as canonical plain values. Returns ------- dict Every field; ``modified`` as a list of ``[name, value]`` pairs and ``sources`` as a list. """ return { "name": self.name, "kind": self.kind, "material": self.material, "digest": self.digest, "status": self.status, "status_reason": self.status_reason, "optmat_version": self.optmat_version, "modified": [list(pair) for pair in self.modified], "base": self.base, "sources": list(self.sources), "reference_temperature": self.reference_temperature, }
[docs] @dataclass(frozen=True) class DiluteScalingCheck: """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 ---------- label : str The population, or the gas, it was evaluated for. material : str The gas. density : float The largest number density of the population, m^-3. temperature : float Temperature in K at that density. wavelength : float Vacuum wavelength in m at which the error is largest over the band. relative_error : float ``(n - 1)_dilute / (n - 1)_optmat - 1``, dimensionless; negative where the dilute law is low. NaN when the check could not be measured. threshold : float The bound above which a warning is raised, relative. reason : str 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 """ label: str material: str density: float temperature: float wavelength: float relative_error: float threshold: float reason: str = ""
[docs] @property def measured(self) -> bool: # numpydoc ignore=RT01 """Whether the error was measured. True unless optmat refused the evaluation (see `reason`). """ return not self.reason
[docs] @property def exceeded(self) -> bool: # numpydoc ignore=RT01 """Whether the error's magnitude is above the threshold. ``abs(relative_error) > threshold`` for a measured check; False for one that was not measured. """ return self.measured and abs(self.relative_error) > self.threshold
[docs] def to_dict(self) -> Mapping[str, object]: """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. """ return { "label": self.label, "material": self.material, "density": self.density, "temperature": self.temperature, "wavelength": self.wavelength if self.measured else None, "relative_error": self.relative_error if self.measured else None, "threshold": self.threshold, "measured": self.measured, "reason": self.reason, }
def _plain(value: object) -> object: """Return a value with tuples as lists and mappings as dicts, recursively. A NumPy scalar becomes the Python value it holds, as in its canonical JSON (:func:`solprop._identity.canonical_json`), so an entry compares and stores as it is identified. """ if isinstance(value, Mapping): return {str(key): _plain(item) for key, item in value.items()} if isinstance(value, (list, tuple)): return [_plain(item) for item in value] if isinstance(value, np.bool_ | np.integer | np.floating): return value.item() return value def _entries(values: Iterable[Mapping[str, object]]) -> tuple[dict[str, object], ...]: """Return entries as plain dicts, each once, sorted by their canonical JSON.""" distinct = { canonical_json(_plain(entry)): cast("dict[str, object]", _plain(entry)) for entry in values } return tuple(distinct[key] for key in sorted(distinct)) def _keyed( entries: Sequence[Mapping[str, object]], fields: Sequence[str] ) -> dict[str, object]: """Key entries by the named fields, so a difference names the entry that moved. The key is the fields' values joined by ``:``; entries that share a key take a numbered suffix, ``#1``, ``#2``, in their order. """ names = [ ":".join(str(entry.get(name) or "-") for name in fields) for entry in entries ] keyed: dict[str, object] = {} counts: dict[str, int] = {} for name, entry in zip(names, entries, strict=True): if names.count(name) == 1: keyed[name] = entry continue counts[name] = counts.get(name, 0) + 1 keyed[f"{name}#{counts[name]}"] = entry return keyed def _stored_entries( document: Mapping[str, object], name: str ) -> list[Mapping[str, object]]: """Return a stored manifest field's entries, keyed or listed. - Returns: its entries; none when it is absent. """ stored = document.get(name) or {} items = stored.values() if isinstance(stored, Mapping) else stored return list(cast("Iterable[Mapping[str, object]]", items)) _SOLID_POLICY: Final = ("material", "axis", "model", "digest", "transparent") """The fields of a solid's entry that identify it; with its bound, they are hashed.""" def _solid_identity(solid: Mapping[str, object]) -> dict[str, object]: """Return the hashed part of a solid's entry: identity and policy. - Returns: its identifying fields, and the absorption bound of a transparent one. """ identity = {name: solid.get(name) for name in _SOLID_POLICY} if solid.get("transparent"): identity["absorption_bound"] = solid.get("absorption_bound") return identity
[docs] def hashed_document(document: Mapping[str, object] | None) -> dict[str, object] | None: """Return the hashed part of a stored manifest, as the stored text holds it. :meth:`MaterialManifest.hashed` of the manifest :meth:`MaterialManifest.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 ---------- document : collections.abc.Mapping or None A stored manifest, or ``None`` for the empty one. Returns ------- dict or None The optmat version, records, species, compositions, solids' identities and policies; ``None`` for 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 """ if document is None: return None hashed = { name: document[name] for name in ("optmat_version", "records", "species", "compositions", "policies") if name in document } hashed["solids"] = _keyed( [_solid_identity(solid) for solid in _stored_entries(document, "solids")], ("material", "axis", "model"), ) return hashed
[docs] @dataclass(frozen=True) class MaterialManifest: """Record the optmat materials of one run: identities, policies and measurements. Built once per run from its mixtures, modes and solids (:func:`solprop.driver.material_output.material_manifest`) and stored in its :class:`~solprop.output.metadata.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 (:meth:`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_version : str The installed optmat's full version string; empty for an empty manifest. selection : collections.abc.Mapping or None :meth:`MaterialSelection.to_dict` of the run's selection, or ``None``. records : tuple of MaterialRecord Every resolved model, each digest once, sorted by material, kind, name and digest. species : tuple of collections.abc.Mapping One entry per optmat-backed population: ``label``, ``species`` and the digests of its ``records``. compositions : tuple of collections.abc.Mapping The named optmat compositions a mixture was built from: ``name``, ``labels`` and ``fractions``. solids : tuple 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 (:meth:`solprop.physdata.glasses.OptmatGlass.run_transparency`). policies : collections.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``, and ``ionisation``: one entry per optmat rate, with its threshold kind, its reference field, its energy-loss convention, its constant energy per event and that energy's bound (:meth:`solprop.nonlinear.optmat_rates.OptmatRate.manifest_entry`). A policy a later phase resolves is recorded as selected, or ``None``. dilute_scaling : tuple of collections.abc.Mapping :meth:`DiluteScalingCheck.to_dict` of each optmat population, measured once per run over the run's band. ranges : tuple of collections.abc.Mapping For each model evaluated outside its qualified intervals: ``material``, ``model``, ``digest`` and the ``outside`` phrases its range warning named. citations : tuple of collections.abc.Mapping The other material objects of the run (supplied or solprop's own): ``object`` (the class), ``name`` and ``citation``. electronic : tuple 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 (:meth:`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 (:meth:`solprop.physdata.nonlinear_data.ElectronicRegions.to_dict`). peak_fields : tuple 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 (:class:`solprop.nonlinear.optmat_rates.PeakFieldReport`). Recorded once the run has run; empty before. raman : tuple 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) """ optmat_version: str = "" selection: Mapping[str, object] | None = None records: tuple[MaterialRecord, ...] = () species: tuple[Mapping[str, object], ...] = () compositions: tuple[Mapping[str, object], ...] = () solids: tuple[Mapping[str, object], ...] = () policies: Mapping[str, object] | None = None dilute_scaling: tuple[Mapping[str, object], ...] = () ranges: tuple[Mapping[str, object], ...] = () citations: tuple[Mapping[str, object], ...] = () electronic: tuple[Mapping[str, object], ...] = () peak_fields: tuple[Mapping[str, object], ...] = () raman: tuple[Mapping[str, object], ...] = () def __post_init__(self) -> None: """Deduplicate every entry and put it in canonical order.""" unique = {entry.digest: entry for entry in self.records} object.__setattr__( self, "records", tuple( sorted( unique.values(), key=lambda r: (r.material, r.kind, r.name, r.digest), ) ), ) for name in ( "species", "compositions", "solids", "dilute_scaling", "ranges", "citations", "electronic", "peak_fields", "raman", ): object.__setattr__(self, name, _entries(getattr(self, name))) if self.selection is not None: object.__setattr__( self, "selection", cast("dict[str, object]", _plain(self.selection)) ) if self.policies is not None: object.__setattr__( self, "policies", cast("dict[str, object]", _plain(self.policies)) )
[docs] @property def empty(self) -> bool: # numpydoc ignore=RT01 """Whether the run took nothing from optmat and selected nothing. True for a run of solprop's own materials only. """ return self.selection is None and not self.records
[docs] def hashed(self) -> dict[str, object] | None: """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'] """ if self.empty: return None records = [record.to_dict() for record in self.records] return { "optmat_version": self.optmat_version, "records": _keyed(records, ("material", "kind", "name")), "species": _keyed(self.species, ("label",)), "compositions": [dict(entry) for entry in self.compositions], "solids": _keyed( [_solid_identity(solid) for solid in self.solids], ("material", "axis", "model"), ), "policies": dict(self.policies or {}), }
[docs] def to_dict(self) -> dict[str, object] | None: """Return the whole manifest as plain values, for a file. Returns ------- dict or None :meth:`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. """ document = self.hashed() if document is None: return None document["selection"] = None if self.selection is None else dict(self.selection) document["solids"] = _keyed(self.solids, ("material", "axis", "model")) document["dilute_scaling"] = [dict(entry) for entry in self.dilute_scaling] document["ranges"] = [dict(entry) for entry in self.ranges] document["citations"] = [dict(entry) for entry in self.citations] document["electronic"] = [dict(entry) for entry in self.electronic] document["peak_fields"] = [dict(entry) for entry in self.peak_fields] document["raman"] = [dict(entry) for entry in self.raman] return document
[docs] @classmethod def from_dict(cls, document: Mapping[str, object] | None) -> "MaterialManifest": """Rebuild a manifest from :meth:`to_dict`. Parameters ---------- document : collections.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 """ if document is None: return cls() try: records = tuple( MaterialRecord( **{ **entry, "modified": tuple( tuple(pair) for pair in cast("list[list[str]]", entry["modified"]) ), "sources": tuple(cast("list[str]", entry["sources"])), } # pyright: ignore[reportArgumentType] - checked by the record ) for entry in _stored_entries(document, "records") ) except (KeyError, TypeError) as error: msg = f"a stored material record is malformed: {error}" raise MaterialError(msg) from error selection = document.get("selection") policies = document.get("policies") return cls( optmat_version=str(document.get("optmat_version", "")), selection=cast("Mapping[str, object] | None", selection), records=records, species=tuple(_stored_entries(document, "species")), compositions=tuple(_stored_entries(document, "compositions")), solids=tuple(_stored_entries(document, "solids")), policies=cast("Mapping[str, object] | None", policies), dilute_scaling=tuple(_stored_entries(document, "dilute_scaling")), ranges=tuple(_stored_entries(document, "ranges")), citations=tuple(_stored_entries(document, "citations")), electronic=tuple(_stored_entries(document, "electronic")), peak_fields=tuple(_stored_entries(document, "peak_fields")), raman=tuple(_stored_entries(document, "raman")), )
[docs] @dataclass(eq=False) class MaterialLog: """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 ---------- seen : set of tuple of str The keys of the warnings already raised. ranges : dict 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. dropped : dict 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). """ seen: set[tuple[str, ...]] = field(default_factory=set) ranges: dict[str, tuple[str, str, set[str]]] = field(default_factory=dict) dropped: dict[tuple[str, float], tuple[float, float, float]] = field( default_factory=dict )
[docs] def record_dropped( self, key: tuple[str, float], extinction: float, absorption: float, wavelength: float, ) -> None: """Add the loss a transparent index dropped in one evaluation. Parameters ---------- key : tuple The model's digest and the absorption bound in 1/m. extinction : float The largest ``k`` the evaluation dropped, dimensionless. absorption : float The largest ``4 pi k / lambda`` it dropped, 1/m. wavelength : float 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) """ known, worst, where = self.dropped.get(key, (0.0, 0.0, math.nan)) if absorption > worst: worst, where = absorption, wavelength self.dropped[key] = (max(known, extinction), worst, where)
[docs] def record_range( self, digest: str, material: str, name: str, parts: Sequence[str] ) -> None: """Add the parts of a band a model was evaluated at outside its intervals. Parameters ---------- digest : str The model's digest. material : str The material it serves. name : str The model's name. parts : sequence of str The phrases naming the parts of the band outside the model's intervals; none when the band is not known. """ _, _, known = self.ranges.setdefault(digest, (material, name, set())) known.update(parts)
[docs] def copy(self) -> "MaterialLog": """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')]) """ return MaterialLog( set(self.seen), { digest: (material, name, set(parts)) for digest, (material, name, parts) in self.ranges.items() }, dict(self.dropped), )
[docs] def range_entries(self) -> tuple[dict[str, object], ...]: """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. """ return tuple( { "material": material, "model": name, "digest": digest, "outside": sorted(parts), } for digest, (material, name, parts) in sorted( self.ranges.items(), key=lambda item: (item[1][0], item[1][1], item[0]) ) )