Source code for solprop.adiabatic

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

r"""Certify adiabatic forward transport through a real index that varies along z.

A radial or Cartesian spectral column propagates with the real longitudinal wave number
:math:`q(z) = \operatorname{Re}k_z`, and the forward-only model drops its coupling to
the backward wave. For a positive real q of bounded variation over the run path, the
exact scalar problem bounds what that drops (SEP 34, section 4.5): with
:math:`\Lambda = \tfrac12\operatorname{TV}(\ln q)`, kinks and declared jumps alike, the
reflected power is at most :math:`R_* = \tanh^2\Lambda` (:func:`reflection_bound`) and
the relative error of the retained forward field at most
:math:`\delta_* = \operatorname{expm1}(\Lambda\tanh\Lambda)`
(:func:`field_error_bound`). The bound is for the linear background problem only.

- :class:`AdiabaticAccuracy` holds the two budgets every propagating column of the
  active band must meet over the whole path.
- :func:`certify_wave_path` and :func:`certify_radial_path` certify a path without
  sampling it: the wave-number square is affine in the number densities, so the
  variation is enclosed piece by piece from each density's
  :class:`solprop.profiles.PathVariation`, with the arithmetic error bounded.
- :class:`AdiabaticAdmission` is the resulting certificate, kept with a run's output as
  plain values by :func:`admission_record` and read back by
  :func:`admission_from_record`.

The bound, the refusals and the enclosure are in ``docs/guide/free-space/flux.md``,
section "The adiabatic certificate".
"""

import itertools
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import Final, cast

import numpy as np
from jaxtyping import Bool, Float, Num

from solprop.constants import C
from solprop.exceptions import MaterialError, TranslationError
from solprop.physdata.glasses import GlassIndex
from solprop.physdata.mixtures import Mixture
from solprop.profiles import PathVariation, ZProfile, profile_identity
from solprop.spatial import SpatialDispersion

__all__ = [
    "AdiabaticAccuracy",
    "AdiabaticAdmission",
    "admission_from_record",
    "admission_record",
    "certify_radial_path",
    "certify_wave_path",
    "field_error_bound",
    "reflection_bound",
]

_UNIT: Final = 2.0**-53
"""The unit roundoff of binary64."""


[docs] @dataclass(frozen=True) class AdiabaticAccuracy: """The budgets a z-varying path must meet to use adiabatic forward transport. These are model budgets chosen by the maintainer, not physical constants or integrator tolerances. Callers may tighten them. Attributes ---------- field_error : float Largest certified relative error of the retained forward field, ``expm1(Lambda tanh Lambda)``, finite and positive. Default 1e-4. reflected_energy : float Largest certified reflected fraction of the power, ``tanh(Lambda)**2``, finite and positive. Default 1e-4. Raises ------ MaterialError If a budget is not finite and positive. Examples -------- >>> from solprop.adiabatic import AdiabaticAccuracy >>> AdiabaticAccuracy().field_error 0.0001 """ field_error: float = 1e-4 reflected_energy: float = 1e-4 def __post_init__(self) -> None: """Refuse a budget that is not finite and positive.""" for name in ("field_error", "reflected_energy"): value = getattr(self, name) if ( isinstance(value, bool) or not isinstance(value, int | float) or not math.isfinite(value) or value <= 0.0 ): raise MaterialError( f"AdiabaticAccuracy.{name} must be finite and positive, " f"got {value!r}" ) object.__setattr__(self, name, float(value))
[docs] def reflection_bound(variation: float | np.ndarray) -> float | np.ndarray: """Return the reflected-power bound ``tanh(Lambda)**2``. Parameters ---------- variation : float or numpy.ndarray ``Lambda``, half the total variation of ``ln q``, nonnegative. Returns ------- float or numpy.ndarray The bound; ``tanh`` is accurate to a few ulps for tiny arguments. Examples -------- >>> from solprop.adiabatic import reflection_bound >>> float(reflection_bound(1e-9)) 1e-18 """ return np.tanh(variation) ** 2
[docs] def field_error_bound(variation: float | np.ndarray) -> float | np.ndarray: """Return the forward-field error bound ``expm1(Lambda tanh Lambda)``. Parameters ---------- variation : float or numpy.ndarray ``Lambda``, half the total variation of ``ln q``, nonnegative. Returns ------- float or numpy.ndarray The relative complex error bound of the retained forward field. Examples -------- >>> from solprop.adiabatic import field_error_bound >>> float(field_error_bound(1e-9)) 1e-18 """ return np.expm1(variation * np.tanh(variation))
[docs] @dataclass(frozen=True, eq=False) class AdiabaticAdmission: """The record that a path met its adiabatic budgets. Attributes ---------- identity : collections.abc.Mapping The represented material path: the material and each density path's structural identity (``None`` for a custom path, which has none). z_span : tuple of float The certified run path ``(z0, z1)`` in m. accuracy : AdiabaticAccuracy The budgets met. variation : float The largest enclosed ``Lambda`` over the propagating columns. reflection : float ``tanh(variation)**2``, the largest reflected-power bound. field_error : float ``expm1(variation tanh variation)``, the largest forward-field bound. worst_kperp_sq : float or None Transverse wave-number square in m^-2 of the column attaining `variation`; ``None`` when no column varies. worst_omega : float or None Its angular frequency in rad/s. omega : numpy.ndarray The certified angular frequencies in rad/s, shape ``(n_omega,)``. spectral_variation : numpy.ndarray The largest ``Lambda`` over the propagating columns at each frequency, zero where none propagates, shape ``(n_omega,)``. support : numpy.ndarray Which columns propagate over the whole path, shape ``(n_modes, n_omega)``; the others are nonpropagating everywhere. jumps : numpy.ndarray Declared jumps of the material inside the path, in m. exact : bool Whether every piece was certified monotone, so that ``variation`` is the attained value up to rounding rather than an upper bound. interpolation_envelope : float Relative error of the run's tabulated operator against the represented path, a separate envelope from the certificate's bounds (SEP 34 section 4.5); zero when no table stands between them. """ identity: Mapping[str, object] z_span: tuple[float, float] accuracy: AdiabaticAccuracy variation: float reflection: float field_error: float worst_kperp_sq: float | None worst_omega: float | None omega: Float[np.ndarray, " n_omega"] = field(repr=False) spectral_variation: Float[np.ndarray, " n_omega"] = field(repr=False) support: Bool[np.ndarray, "n_modes n_omega"] = field(repr=False) jumps: Float[np.ndarray, " n_jumps"] = field(repr=False) exact: bool = True interpolation_envelope: float = 0.0 def __post_init__(self) -> None: """Freeze the arrays.""" for name in ("omega", "spectral_variation", "support", "jumps"): values = np.array(getattr(self, name)) values.setflags(write=False) object.__setattr__(self, name, values)
@dataclass(frozen=True) class _Pieces: """The density paths' enclosures on the union of their pieces. Attributes ---------- knots : numpy.ndarray Union of the piece edges in m. first, last, variation, low, high : numpy.ndarray Per path and piece, shape ``(n_paths, n_pieces)``, as in :class:`solprop.profiles.PathVariation`. monotone : numpy.ndarray Per path and piece, whether the enclosure is certified monotone. """ knots: Float[np.ndarray, " n_knots"] first: Float[np.ndarray, "n_paths n_pieces"] last: Float[np.ndarray, "n_paths n_pieces"] variation: Float[np.ndarray, "n_paths n_pieces"] low: Float[np.ndarray, "n_paths n_pieces"] high: Float[np.ndarray, "n_paths n_pieces"] monotone: Bool[np.ndarray, "n_paths n_pieces"] @dataclass(frozen=True) class _AffineSquare: """The wave-number square ``s = base + sum_i b_i rho_i`` of every column. Attributes ---------- base : numpy.ndarray ``(omega/c)^2 Re(epsilon) - k_perp^2`` in m^-2, shape ``(n_modes, n_omega)``. slope : numpy.ndarray ``b_i = (omega/c)^2 Re(chi_i)``, shape ``(n_paths, n_omega)``. pieces : _Pieces The density paths' aligned enclosures. kperp_sq : numpy.ndarray Transverse squares in m^-2, for the rounding scale. """ base: Float[np.ndarray, "n_modes n_omega"] slope: Float[np.ndarray, "n_paths n_omega"] pieces: _Pieces kperp_sq: Float[np.ndarray, " n_modes"] @property def magnitude(self) -> Float[np.ndarray, "n_modes n_omega"]: """Return the scale S of the terms that form s, for its rounding error. - Returns: ``|base + k_perp^2| + sum_i |b_i| max|rho_i| + k_perp^2`` in m^-2. """ pieces = self.pieces scale = np.max( np.abs(np.concatenate([pieces.low, pieces.high], axis=1)), axis=1, initial=0.0, ) return ( np.abs(self.base + self.kperp_sq[:, None]) + np.sum(np.abs(self.slope) * scale[:, None], axis=0)[None, :] + self.kperp_sq[:, None] ) def at(self, values: Float[np.ndarray, " n_paths"]) -> np.ndarray: """Return s for one density per path. - Returns: the square s in m^-2, shape ``(n_modes, n_omega)``. """ return self.base + np.sum(self.slope * values[:, None], axis=0)[None, :] def _term( self, change: np.ndarray, reference: np.ndarray, magnitude: np.ndarray ) -> np.ndarray: """Return ``|Delta ln q|`` from ``Delta s / s``, enlarged by its rounding. - ``change``: the change of s, formed from the density changes, not by subtraction. - ``reference``: the square s at the start of the change. - ``magnitude``: the scale S of the terms forming s. - Returns: ``|log1p(change/reference)| / 2`` times one plus its relative error bound; zero where the reference is not positive (a crossing). """ terms = self.slope.shape[0] + 3 with np.errstate(divide="ignore", invalid="ignore"): ratio = np.where(reference > 0.0, change / reference, 0.0) value = np.abs(0.5 * np.log1p(np.maximum(ratio, -1.0 + 2 * _UNIT))) # Forming the difference and the ratio costs a few unit roundoffs; # s itself carries 4u S of cancellation error towards cutoff; log1p # amplifies a relative error of its argument by its condition number. relative = 2.0 * ( _log_condition(ratio) * (terms * _UNIT + 4.0 * _UNIT * magnitude / np.abs(reference)) + 2.0 * _UNIT ) return np.where(reference > 0.0, value * (1.0 + relative), 0.0) def _box(self, j: int, low: np.ndarray, magnitude: np.ndarray) -> np.ndarray: """Return the bound ``sum_i |b_i| TV(rho_i) / (2 s_min)`` on piece j. - ``magnitude``: the scale S of the terms forming s. - Returns: the bound of ``TV(ln q)`` on the piece, enlarged by its rounding, and infinite where ``s_min`` is not positive. """ terms = self.slope.shape[0] + 4 change = np.sum( np.abs(self.slope) * self.pieces.variation[:, j : j + 1], axis=0 )[None, :] with np.errstate(divide="ignore", invalid="ignore"): relative = 2.0 * (terms * _UNIT + 4.0 * _UNIT * magnitude / np.abs(low)) return np.where(low > 0.0, change / (2.0 * low) * (1.0 + relative), np.inf) def enclose( self, ) -> tuple[np.ndarray, np.ndarray, np.ndarray, bool]: """Enclose ``Lambda`` and the range of s for every column. - Returns: ``Lambda`` (meaningful where s stays positive), the lowest and highest enclosed s, each of shape ``(n_modes, n_omega)``, and whether every varying piece was monotone, so that ``Lambda`` is attained. """ pieces, slope = self.pieces, self.slope magnitude = self.magnitude shape = self.base.shape lowest = np.full(shape, np.inf) highest = np.full(shape, -np.inf) total = np.zeros(shape) exact = True n_pieces = pieces.knots.size - 1 for j in range(n_pieces): first, last = pieces.first[:, j], pieces.last[:, j] s_first, s_last = self.at(first), self.at(last) moves = slope * (last - first)[:, None] same_way = np.all(moves >= 0.0, axis=0) | np.all(moves <= 0.0, axis=0) monotone = (bool(np.all(pieces.monotone[:, j])) & same_way)[None, :] ends = slope * pieces.low[:, j : j + 1], slope * pieces.high[:, j : j + 1] box_low = self.base + np.sum(np.minimum(*ends), axis=0)[None, :] box_high = self.base + np.sum(np.maximum(*ends), axis=0)[None, :] low = np.where(monotone, np.minimum(s_first, s_last), box_low) lowest = np.minimum(lowest, low) highest = np.maximum( highest, np.where(monotone, np.maximum(s_first, s_last), box_high) ) if np.any(pieces.variation[:, j] > 0.0): smooth = self._term(np.sum(moves, axis=0)[None, :], s_first, magnitude) total = total + np.where(monotone, smooth, self._box(j, low, magnitude)) exact = exact and bool(np.all(monotone)) if j > 0: before = pieces.last[:, j - 1] change = np.sum(slope * (first - before)[:, None], axis=0)[None, :] if np.any(change != 0.0): total = total + self._term(change, self.at(before), magnitude) # Lambda is half TV(ln q); the sum rounds once per term. return 0.5 * total * (1.0 + (2 * n_pieces + 1) * _UNIT), lowest, highest, exact def _variation_of(path: ZProfile, start: float, end: float) -> PathVariation: """Return a path's enclosure, refusing one that cannot give it. - ``start``, ``end``: the interval in m. """ try: return path.variation(start, end) except TranslationError as error: raise MaterialError( f"the adiabatic certificate needs a bounded variation of {path!r}: {error}" ) from error def _pieces(paths: Sequence[ZProfile], start: float, end: float) -> _Pieces: """Collect every path's enclosure on the union of their pieces. - ``paths``: the density paths, at least one. - ``start``, ``end``: the run path in m. """ knots = np.unique( np.concatenate([_variation_of(p, start, end).knots for p in paths]) ) rows = [ [_variation_of(p, a, b).collapse() for a, b in itertools.pairwise(knots)] for p in paths ] def table(name: str) -> np.ndarray: """Return one field of every collapsed piece, paths by pieces.""" return np.array([[float(getattr(c, name)[0]) for c in row] for row in rows]) return _Pieces( knots, table("first"), table("last"), table("variation"), table("low"), table("high"), np.array([[bool(c.monotone[0]) for c in row] for row in rows]), ) def _log_condition(ratio: np.ndarray) -> np.ndarray: """Return the relative condition number of ``log1p`` at each argument.""" with np.errstate(divide="ignore", invalid="ignore"): value = np.abs(ratio / ((1.0 + ratio) * np.log1p(ratio))) return np.where(np.abs(ratio) < 1e-8, 1.0, value) def _wavelength_text(omega: float) -> str: """Return a vacuum wavelength for a message. - ``omega``: angular frequency in rad/s. """ return f"{2 * math.pi * C / omega * 1e9:.6g} nm"
[docs] def certify_wave_path( # noqa: PLR0917 - the affine model's arrays and the run path omega: Float[np.ndarray, " n_omega"], permittivity: Num[np.ndarray, " n_omega"], susceptibilities: Num[np.ndarray, "n_paths n_omega"], paths: Sequence[ZProfile], kperp_sq: Float[np.ndarray, " n_modes"], z_span: tuple[float, float], accuracy: AdiabaticAccuracy | None = None, *, identity: Mapping[str, object] | None = None, ) -> AdiabaticAdmission: r"""Certify the columns of a material whose wave-number square is affine in z. The longitudinal square of every column is :math:`s = (\omega/c)^2(\varepsilon + \sum_i\rho_i(z)\chi_i) - k_\perp^2` (``docs/guide/free-space/flux.md`` gives the enclosure). Parameters ---------- omega : numpy.ndarray Finite positive angular frequencies in rad/s, shape ``(n_omega,)``. permittivity : numpy.ndarray The constant part ``epsilon`` of the relative permittivity, shape ``(n_omega,)``. susceptibilities : numpy.ndarray Per-density susceptibility ``chi_i``, in the inverse unit of the paths, shape ``(n_paths, n_omega)``. paths : sequence of ZProfile The densities ``rho_i(z)``; each must enclose its variation. kperp_sq : numpy.ndarray Transverse wave-number squares in m^-2, finite and nonnegative, shape ``(n_modes,)``. z_span : tuple of float The run path ``(z0, z1)`` in m, finite with ``z0 < z1``. accuracy : AdiabaticAccuracy or None, optional The budgets; ``None`` takes the defaults. identity : collections.abc.Mapping or None, optional The represented path's identity, recorded in the admission. Returns ------- AdiabaticAdmission The record of a path within budget. Raises ------ MaterialError If a budget is exceeded (naming the worst column, its frequency and the bound), a column crosses ``q = 0`` over the path, the imaginary index varies, a path cannot enclose its variation, or an input is invalid. Examples -------- >>> import numpy as np >>> from solprop.adiabatic import certify_wave_path >>> from solprop.profiles import Linear >>> omega = np.array([2.35e15]) >>> admission = certify_wave_path( ... omega, np.ones(1), np.array([[1e-3]]), [Linear(0.0, 1.0, 1e-3)], ... np.zeros(1), (0.0, 1e-3)) >>> f"{admission.variation:.6e}" '2.498751e-04' """ accuracy = AdiabaticAccuracy() if accuracy is None else accuracy start, end = (float(v) for v in z_span) if not (math.isfinite(start) and math.isfinite(end) and end > start): raise MaterialError(f"the certified path needs finite z0 < z1, got {z_span}") omega = np.asarray(omega, dtype=float) kperp_sq = np.asarray(kperp_sq, dtype=float) permittivity = np.asarray(permittivity, dtype=complex) chi = np.asarray(susceptibilities, dtype=complex).reshape(len(paths), omega.size) if ( omega.ndim != 1 or not np.all(np.isfinite(omega)) or np.any(omega <= 0.0) or permittivity.shape != omega.shape or not np.all(np.isfinite(permittivity)) or not np.all(np.isfinite(chi)) ): raise MaterialError( "the certificate needs finite positive frequencies and finite material data" ) if kperp_sq.ndim != 1 or not np.all(np.isfinite(kperp_sq)) or np.any(kperp_sq < 0): raise MaterialError("transverse wave-number squares must be finite and >= 0") wave_sq = (omega / C) ** 2 base = wave_sq[None, :] * np.real(permittivity)[None, :] - kperp_sq[:, None] if paths: pieces = _pieces(paths, start, end) else: none = np.empty((0, 1)) pieces = _Pieces( np.array([start, end]), none, none, none, none, none, none.astype(bool) ) jump_sizes = np.abs(pieces.first[:, 1:] - pieces.last[:, :-1]) varies = np.sum(pieces.variation, axis=1) + np.sum(jump_sizes, axis=1) > 0.0 if np.any(varies): # Any loss makes Im k_z = Im(k**2) / (2 Re k_z) vary with Re k_z along a # varying path, even when the absorbing component's own density is fixed. lossy = np.any(np.imag(chi) != 0.0, axis=0) | (np.imag(permittivity) != 0.0) if np.any(lossy): where = int(np.argmax(lossy)) raise MaterialError( "the adiabatic certificate needs a real index along a varying path, " f"and the imaginary index varies at {_wavelength_text(omega[where])}: " "a nonconstant absorbing path is not supported (uniform loss is)" ) square = _AffineSquare(base, wave_sq[None, :] * np.real(chi), pieces, kperp_sq) total, lowest, highest, exact = square.enclose() shape = total.shape propagating = lowest > 0.0 nonpropagating = highest <= 0.0 crossing = ~(propagating | nonpropagating) if np.any(varies) and np.any(crossing): mode, bin_ = np.unravel_index(int(np.argmax(crossing)), shape) raise MaterialError( "a column crosses q = 0 along the path (propagating at one point and not " f"at another, or not shown otherwise): k_perp^2 = {kperp_sq[mode]:.6g} " f"m^-2 at {_wavelength_text(omega[bin_])}, with q^2 between " f"{lowest[mode, bin_]:.6g} and {highest[mode, bin_]:.6g} m^-2; " f"{int(np.count_nonzero(crossing))} of {crossing.size} columns cross" ) variation = np.where(propagating, total, 0.0) if not np.any(varies): variation = np.zeros(shape) worst = int(np.argmax(variation)) if variation.size else 0 mode, bin_ = np.unravel_index(worst, shape) largest = float(variation[mode, bin_]) if variation.size else 0.0 reflection = float(reflection_bound(largest)) field_error = float(field_error_bound(largest)) if field_error > accuracy.field_error or reflection > accuracy.reflected_energy: failing = int( np.count_nonzero( (field_error_bound(variation) > accuracy.field_error) | (reflection_bound(variation) > accuracy.reflected_energy) ) ) over = [ f"field error {field_error:.3g} > {accuracy.field_error:.3g}" if field_error > accuracy.field_error else "", f"reflected energy {reflection:.3g} > {accuracy.reflected_energy:.3g}" if reflection > accuracy.reflected_energy else "", ] raise MaterialError( "the z-varying medium exceeds its adiabatic budget: " + " and ".join(o for o in over if o) + f" at the worst column, k_perp^2 = {kperp_sq[mode]:.6g} m^-2 at " f"{_wavelength_text(omega[bin_])} (Lambda = {largest:.6g}, half the total " f"variation of ln q over z = {start:g} to {end:g} m); {failing} of " f"{int(np.count_nonzero(propagating))} propagating columns exceed a " "budget. Smooth the gradient, move the band away from cutoff, or pass a " "looser AdiabaticAccuracy" ) return AdiabaticAdmission( identity=dict(identity or {}), z_span=(start, end), accuracy=accuracy, variation=largest, reflection=reflection, field_error=field_error, worst_kperp_sq=float(kperp_sq[mode]) if largest > 0.0 else None, worst_omega=float(omega[bin_]) if largest > 0.0 else None, omega=omega, spectral_variation=np.max(variation, axis=0, initial=0.0), support=propagating, jumps=np.unique( np.concatenate([np.asarray(p.jumps, dtype=float) for p in paths]) if paths else np.empty(0) ), exact=exact, )
def _material_terms( dispersion: SpatialDispersion, omega: Float[np.ndarray, " n_omega"] ) -> tuple[np.ndarray, np.ndarray, list[ZProfile], dict[str, object]]: """Split a spatial medium into its affine permittivity and density paths. - ``omega``: active angular frequencies in rad/s. - Returns: constant permittivity, per-path susceptibilities, the density paths and the material identity. """ medium = dispersion.medium material = medium.material if isinstance(material, Mixture): paths = [c.density for c in material.components] chi = np.array( [ np.asarray(c.species.susceptibility.susceptibility(omega)) for c in material.components ] ) name = "mixture of " + ", ".join(material.labels) permittivity = np.ones(omega.size, dtype=complex) elif medium.susceptibility is not None and not isinstance(material, GlassIndex): paths = [medium.density] chi = np.asarray(medium.susceptibility.susceptibility(omega))[None, :] name = getattr(material, "name", None) or str(material) permittivity = np.ones(omega.size, dtype=complex) else: paths = [] chi = np.empty((0, omega.size), dtype=complex) name = repr(material) permittivity = medium.index(omega) ** 2 identities: list[object] = [] for path in paths: try: identities.append(profile_identity(path)) except TranslationError: identities.append(None) return permittivity, chi, paths, {"material": name, "paths": identities}
[docs] def certify_radial_path( dispersion: SpatialDispersion, kperp_sq: Float[np.ndarray, " n_modes"], z_span: tuple[float, float], accuracy: AdiabaticAccuracy | None = None, ) -> AdiabaticAdmission: """Certify a spatial medium's z-varying path for every column of a radial grid. Parameters ---------- dispersion : solprop.spatial.SpatialDispersion The medium and the temporal grid, whose active band is certified. kperp_sq : numpy.ndarray Transverse wave-number squares in m^-2, for a radial grid ``k_r**2``. z_span : tuple of float The run path ``(z0, z1)`` in m. accuracy : AdiabaticAccuracy or None, optional The budgets; ``None`` takes the defaults. Returns ------- AdiabaticAdmission The record of a path within budget; a uniform medium is admitted with zero variation. Raises ------ MaterialError As :func:`certify_wave_path`. """ grid = dispersion.grid omega = np.asarray(grid.omega[grid.active_mask], dtype=float) permittivity, chi, paths, identity = _material_terms(dispersion, omega) return certify_wave_path( omega, permittivity, chi, paths, np.asarray(kperp_sq, dtype=float), z_span, accuracy, identity=identity, )
[docs] def admission_record(admission: AdiabaticAdmission) -> dict[str, object]: """Return a path certificate as plain values, for a record that outlives the run. The certificate's scope is the linear background's forward coordinates, not the nonlinear run or an omitted reflected field (SEP 34 section 4.5). Its path identity is kept as text, and a certificate already read from a record keeps that text. Parameters ---------- admission : solprop.adiabatic.AdiabaticAdmission The certificate. Returns ------- dict The values :func:`admission_from_record` rebuilds it from. """ identity = admission.identity return { "scope": "linear-background forward field", "z_span": admission.z_span, "field_error_budget": admission.accuracy.field_error, "reflected_energy_budget": admission.accuracy.reflected_energy, "variation": admission.variation, "field_error": admission.field_error, "reflection": admission.reflection, "worst_kperp_sq": admission.worst_kperp_sq, "worst_omega": admission.worst_omega, "exact": admission.exact, "jumps": admission.jumps, "interpolation_envelope": admission.interpolation_envelope, "identity": identity["recorded"] if set(identity) == {"recorded"} else repr(dict(identity)), "omega": admission.omega, "spectral_variation": admission.spectral_variation, "support": admission.support, }
[docs] def admission_from_record(record: Mapping[str, object]) -> AdiabaticAdmission: """Rebuild a varying path's certificate from its output record. The inverse of :func:`admission_record`. The path's structural identity is kept as the text it was recorded as. Parameters ---------- record : collections.abc.Mapping The ``admission`` entry of a ``flux_plan`` record, as held in memory or as read back from a file. Returns ------- AdiabaticAdmission The certificate. """ def _number(name: str) -> float: """Return one stored scalar.""" return float(cast("float", record[name])) def _optional(name: str) -> float | None: """Return one stored scalar that may be absent. - Returns: the value, or None where it was not recorded. """ value = record.get(name) return None if value is None else float(cast("float", value)) span = cast("Sequence[float]", record["z_span"]) return AdiabaticAdmission( identity={"recorded": record["identity"]}, z_span=(float(span[0]), float(span[1])), accuracy=AdiabaticAccuracy( field_error=_number("field_error_budget"), reflected_energy=_number("reflected_energy_budget"), ), variation=_number("variation"), reflection=_number("reflection"), field_error=_number("field_error"), worst_kperp_sq=_optional("worst_kperp_sq"), worst_omega=_optional("worst_omega"), omega=_recorded_array(record["omega"], float), spectral_variation=_recorded_array(record["spectral_variation"], float), support=_recorded_array(record["support"], bool), jumps=_recorded_array(record["jumps"], float), exact=bool(record["exact"]), interpolation_envelope=_number("interpolation_envelope"), )
def _recorded_array(value: object, dtype: type) -> np.ndarray: """Return an array as held in memory or as read back from a file. A record written to JSON or HDF5 and read back nests each array as the ``{"__ndarray__": ...}`` form of :func:`solprop.output.serialisation.serialise`. Every array of a certificate is real or boolean, so there is no imaginary part to rejoin; this module sits below the output layer and does not import its decoder. """ if isinstance(value, Mapping) and "__ndarray__" in value: return np.asarray(value["__ndarray__"], dtype=dtype) return np.asarray(value, dtype=dtype)