# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""Resolve material declarations and population selections at the driver boundary.
A run's fill from its keywords: :func:`capillary_fill` resolves one material
declaration (a gas, its name, a mapping of fractions or a
:class:`~solprop.physdata.mixtures.Mixture`) with its pressure, temperature and
explicit initial populations into the run's mixture, and :func:`mixture_profiles`
gives that mixture's density and total-pressure profiles for the statistics.
:class:`ResponseSelection` keeps the public response choices a
:meth:`~solprop.driver.simulation.Simulation.with_mixture` update applies again, and
``_mixture_reuse`` says what such an update may keep of the translation it replaces:
the undamped Raman kernels and the sampled operator expansions whose inputs the new
mixture leaves unchanged. Of the four ``mixtures`` modules, one per layer, this is the
driver's declaration resolution: :mod:`solprop.physdata.mixtures` is the type,
:mod:`solprop.nonlinear.mixtures` the response selection and
:mod:`solprop.processing.mixtures` the analysis of saved planes.
"""
import logging
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, replace
from typing import TYPE_CHECKING
import numpy as np
from jaxtyping import Float
from solprop.constants import ROOM_TEMPERATURE
from solprop.exceptions import DriverError
from solprop.gasflow import VacuumEnd
from solprop.modes.protocol import ParameterisedMode
from solprop.nonlinear.ionisation import IntegrationPolicy, IonisationRate
from solprop.nonlinear.mixtures import responses_for
from solprop.nonlinear.optmat_rates import bind_reference_field
from solprop.nonlinear.raman import (
DampedOscillator,
MolecularOptions,
RamanResponse,
RotationalLines,
)
from solprop.output.serialisation import serialise
from solprop.physdata import Gas, Mixture, is_air, species
from solprop.physdata.mixtures import Pressure
from solprop.physdata.selection import MaterialSelection
from solprop.physdata.sellmeier import GasSusceptibility
from solprop.profiles import (
FromCallable,
Sum,
ZProfile,
_checked_temperature,
_same_temperature,
_temperature_text,
)
from solprop.translate.expansion import ParameterExpansion
from solprop.translate.problem import PropagationProblem, TranslationReuse
from solprop.translate.routes import transverse_of
if TYPE_CHECKING:
from solprop.driver.simulation import Simulation
__all__ = [
"ResponseSelection",
"capillary_fill",
"mixture_profiles",
]
logger = logging.getLogger(__name__)
[docs]
@dataclass(frozen=True)
class ResponseSelection:
"""Retain the public response choices when updating a capillary fill.
Attributes
----------
kerr : bool
Whether to include instantaneous electronic responses.
thg : bool
Whether to retain third harmonics on the field grid.
plasma : bool, IonisationRate or Mapping
Global or per-label plasma selection.
raman : bool, sequence of str or Mapping
Global or per-label Raman term selection.
wavelength : float
Reference wavelength in m, the carrier of the default rates.
envelope : bool
Preserve the envelope plasma selection when replacing a fill.
length : float or None
The run's length in m, over which a temperature path's Raman reference
temperature is averaged.
selection : MaterialSelection or None
The run's material selection, under which an optmat-resolved fill takes its
Raman response from optmat and ``plasma=True`` takes optmat's rates.
reference_field : float or None
The input's peak field in V/m, at which an optmat rate's constant energy
per event is taken; ``None`` leaves the rates unbound.
field_range : tuple of float or None
The field amplitudes in V/m the run tabulates its rates over.
plasma_integration : {'band', 'trapezoid'} or None
The field plasma column's running-integral rule (SEP 18); ``None`` takes the
response's default.
"""
kerr: bool
thg: bool
plasma: bool | IonisationRate | Mapping[str, bool | IonisationRate]
raman: bool | Sequence[str] | Mapping[str, bool | MolecularOptions]
wavelength: float
envelope: bool = False
length: float | None = None
selection: MaterialSelection | None = None
reference_field: float | None = None
field_range: tuple[float, float] | None = None
plasma_integration: IntegrationPolicy | None = None
[docs]
def build(self, mixture: Mixture) -> tuple[object, ...]:
"""Build the selected responses using the updated component declarations.
Parameters
----------
mixture : Mixture
Ordered material, temperature and initial populations.
Returns
-------
tuple
Response declarations in mixture order, an optmat rate bound to the
run's reference field.
"""
responses = responses_for(
mixture,
kerr=self.kerr,
thg=self.thg,
plasma=self.plasma,
raman=self.raman,
wavelength=self.wavelength,
envelope=self.envelope,
length=self.length,
selection=self.selection,
plasma_integration=self.plasma_integration,
)
if self.reference_field is None:
return responses
return bind_reference_field(responses, self.reference_field, self.field_range)
_PRESSURE_FORM_ENTRIES = 2
"""Entries in either of the two pair forms of the ``pressure`` keyword."""
[docs]
def capillary_fill(
material: Gas | str | Mapping[str, float] | Mixture,
pressure: Pressure | None,
*,
length: float,
temperature: float | ZProfile | None,
floor: float | None,
susceptibility: GasSusceptibility | None,
preionisation: float | ZProfile | Mapping[str, float | ZProfile] | None,
radius: float | ZProfile | None = None,
vacuum_end: VacuumEnd | None = None,
selection: MaterialSelection | None = None,
) -> Mixture:
"""Resolve one material declaration and explicit initial populations.
Parameters
----------
material : Gas, str, Mapping or Mixture
A built-in gas, mole fractions or a complete mixture declaration.
pressure : float, sequence, ZProfile or None
Total pressure in bar; None uses one bar for a built-in gas or fractions.
A supplied Mixture requires None because it already carries its paths.
length : float
Capillary length in m, needed by endpoint pressure pairs.
temperature : float, ZProfile or None
Fill temperature in K, or a path of it along z in m; ``None`` is 293.15 K for a
new fill. An existing mixture carries its own temperature: beside it this
must be ``None`` or the mixture's own (the same number or path object).
floor : float or None
Pressure floor in bar for a new fill; incompatible with an existing mixture.
susceptibility : GasSusceptibility or None
Optical override for a single built-in gas only.
preionisation : float, ZProfile, Mapping or None
Initial ionised fractions in [0, 1], globally or per label, each a number or a
path along z in m. None retains the mixture's declarations; omitted mapping
labels retain their declarations.
radius : float, ZProfile or None, optional
Core radius in m of a circular hollow guide. Given, a pressure pair or
(z, p) pair becomes the steady flow of :func:`solprop.gasflow.steady_fill`,
which follows the bore and chokes a vacuum end; ``None`` (a rectangular
guide, or a mode set without a core radius) keeps the uniform law and the
numerical floor. A constant pressure or a supplied profile does not take it.
vacuum_end : {'choked', 'floor'} or None, optional
How an outer end below its choked pressure is treated; ``None`` chokes it
where `radius` is given. Refused beside an existing mixture, which carries
its own paths.
selection : MaterialSelection or None, optional
Resolve a built-in gas's name, a fraction mapping's names and ``"air"`` from
optmat under this selection; ``None`` is ``MaterialSelection()``. An
existing mixture is taken as it is.
Returns
-------
Mixture
Ordered species, density paths and initial fractions.
Raises
------
DriverError
If pressure, temperature or optical arguments conflict, or a label is
unknown.
"""
if isinstance(material, Mixture):
if temperature is not None and not _same_temperature(
_checked_temperature(temperature, "the run"), material.temperature
):
raise DriverError(
"the Mixture carries its own temperature "
f"({_temperature_text(material.temperature)}), and "
f"temperature={temperature!r} was given beside it: omit temperature=, "
"or build the Mixture at the temperature you mean",
parameter=("gas", "temperature"),
)
if pressure is not None or floor is not None or vacuum_end is not None:
given = {
"pressure": pressure,
"pressure_floor": floor,
"vacuum_end": vacuum_end,
}
raise DriverError(
"Mixture carries its pressure paths; omit pressure, pressure_floor "
"and vacuum_end (a mixture of independent partial pressures is not "
"one flow, and a shared fill was built with its own ends)",
parameter=(
"gas",
*(name for name, value in given.items() if value is not None),
),
rule="mixture-carries-pressure",
)
if susceptibility is not None:
raise DriverError(
"Mixture carries species susceptibilities; omit susceptibility",
parameter=("gas", "susceptibility"),
rule="mixture-carries-susceptibility",
)
mixture = material
else:
temperature = ROOM_TEMPERATURE if temperature is None else temperature
# The bore shapes only a fill built here from end pressures; a supplied
# profile is used as given, and the constructor warns if it is boreless.
bore = radius if isinstance(pressure, Sequence) else None
if isinstance(pressure, Sequence) and len(pressure) != _PRESSURE_FORM_ENTRIES:
raise DriverError(
"pressure must be a number, profile, (p_in, p_out) or (z, p) pair",
parameter="pressure",
)
if isinstance(material, Mapping):
if susceptibility is not None:
raise DriverError(
"fraction mappings carry species optics; omit susceptibility",
parameter=("gas", "susceptibility"),
rule="mixture-carries-susceptibility",
)
fractions = {
species(name, selection=selection): fraction
for name, fraction in material.items()
}
elif is_air(material):
# The convenience the interface promises: "air" is a nitrogen/oxygen
# mixture with separate channels, not the dispersion-only Gas.Air entry.
if susceptibility is not None:
raise DriverError(
'"air" is a mixture of nitrogen and oxygen and carries their '
"susceptibilities; omit susceptibility, or build the Mixture "
"yourself",
parameter=("gas", "susceptibility"),
rule="mixture-carries-susceptibility",
)
mixture = Mixture.air(
1.0 if pressure is None else pressure,
temperature=temperature,
argon=False,
length=length,
floor=floor,
radius=bore,
vacuum_end=vacuum_end,
selection=selection,
)
return _with_initial_populations(mixture, preionisation)
else:
selected = species(material, selection=selection)
if susceptibility is not None:
selected = replace(selected, susceptibility=susceptibility)
fractions = {selected: 1.0}
mixture = Mixture.fill(
fractions,
1.0 if pressure is None else pressure,
temperature=temperature,
length=length,
floor=floor,
radius=bore,
vacuum_end=vacuum_end,
)
return _with_initial_populations(mixture, preionisation)
def _with_initial_populations(
mixture: Mixture,
preionisation: float | ZProfile | Mapping[str, float | ZProfile] | None,
) -> Mixture:
"""Retain unspecified populations when overriding initial ionised fractions.
- ``preionisation``: global or labelled initial fractions in [0, 1], each a number
or a path along z in m.
"""
if preionisation is None:
return mixture
if isinstance(preionisation, Mapping):
unknown = set(preionisation) - set(mixture.labels)
if unknown:
paths = tuple(f'preionisation["{label}"]' for label in sorted(unknown))
raise DriverError(
f"unknown preionisation component labels: {sorted(unknown)}",
parameter=paths[0] if len(paths) == 1 else paths,
)
values = preionisation
else:
values = dict.fromkeys(mixture.labels, preionisation)
return replace(
mixture,
components=tuple(
replace(
component,
preionisation=values.get(component.label, component.preionisation),
)
for component in mixture.components
),
)
[docs]
def mixture_profiles(
mixture: Mixture, *, pressure: bool = False
) -> dict[str, ZProfile]:
"""Return the total density and available total-pressure statistic paths.
Parameters
----------
mixture : Mixture
Ordered material populations.
pressure : bool, optional
For independent densities, include the sum of partial pressures obtained
by inverting each species' equation of state at the declared temperature
(at each position's own, for a temperature path).
Used to preserve an existing pressure statistic after a material update.
Returns
-------
dict
Density in m^-3 and, for a shared fill, pressure in bar.
"""
paths = tuple(component.density for component in mixture.components)
result = {"density": paths[0] if len(paths) == 1 else Sum(paths)}
if mixture.shared is not None:
result["pressure"] = mixture.shared
elif pressure:
total = result["density"]
result["pressure"] = FromCallable(
_PartialPressureSum(mixture), total.z_span, total.breakpoints
)
return result
@dataclass(frozen=True)
class _PartialPressureSum:
"""Evaluate the declared partial-EOS pressure diagnostic, in bar."""
mixture: Mixture
def __call__(self, z: Float[np.ndarray, " n_z"]) -> Float[np.ndarray, " n_z"]:
"""Sum the EOS-inverted partial pressures at the requested positions.
- ``z``: positions in m, shape (n_z,).
- Returns: total pressure diagnostic in bar, shape (n_z,).
"""
temperature = self.mixture.temperature
kelvin = (
[float(value) for value in temperature(z)]
if isinstance(temperature, ZProfile)
else [temperature] * np.size(z)
)
return np.sum(
[
[
component.species.equation_of_state.pressure(float(value), local)
for value, local in zip(component.density(z), kelvin, strict=True)
]
for component in self.mixture.components
],
axis=0,
)
def _simulation_mixture(simulation: "Simulation") -> Mixture:
"""Require a material declaration the update can identify by component."""
if simulation.medium is not None and isinstance(
simulation.medium.material, Mixture
):
return simulation.medium.material
materials = [getattr(mode, "mixture", None) for mode in simulation.modes]
if not materials or not isinstance(materials[0], Mixture):
raise DriverError("with_mixture needs a Mixture in the modes or spatial medium")
material = materials[0]
for index, other in enumerate(materials[1:], 1):
if serialise(other) != serialise(material):
raise DriverError(f"mode {index} carries a different mixture")
return material
def _same_operator_function(
source: "Simulation",
updated: "Simulation",
old: Mixture,
new: Mixture,
expansion: ParameterExpansion | None,
) -> ParameterExpansion | None:
"""Keep terms only when every dependency outside their axes is unchanged.
- ``expansion``: previously sampled coefficients and axis names.
- Returns: the old coefficients when the function is identical, else None with a
log.
"""
if source.settings.prefactor_index != updated.settings.prefactor_index:
logger.info("Mixture update: expansion reuse refused; prefactor_index changed")
return None
if expansion is None:
return None
if len(old.components) > 1 and (
(old.shared is None) != (new.shared is None)
or (
old.shared is not None
and (old.fractions != new.fractions or old.temperature != new.temperature)
)
):
logger.info(
"Mixture update: rebuild expansion; fill fractions, EOS temperature "
"or parameterisation changed"
)
return None
positions = np.asarray(expansion.z_span)
if source.medium is not None and updated.medium is not None:
paths = [(source.medium.parameter_paths, updated.medium.parameter_paths)]
else:
paths = [
(before.parameter_paths, after.parameter_paths)
for before, after in zip(source.modes, updated.modes, strict=True)
if isinstance(before, ParameterisedMode)
and isinstance(after, ParameterisedMode)
]
for before_paths, after_paths in paths:
for name, path in before_paths.items():
if name in expansion.parameters:
continue
other = after_paths.get(name)
if (
other is None
or not other.is_constant
or not np.array_equal(path(positions), other(positions))
):
logger.info(
"Mixture update: rebuild expansion; fixed parameter %s changed",
name,
)
return None
return expansion
def _mixture_reuse(
source: "Simulation",
updated: "Simulation",
old: Mixture,
new: Mixture,
problem: PropagationProblem,
) -> TranslationReuse:
"""Collect eligible immutable translation data after a material-path update."""
before = {
response.species or old.labels[0]: response
for response in source.responses
if isinstance(response, RamanResponse)
}
after = {
response.species or new.labels[0]: response
for response in updated.responses
if isinstance(response, RamanResponse)
}
kernels = {}
for leaf in problem.responses.raman_terms:
if _undamped_model_key(before[leaf.label]) == _undamped_model_key(
after[leaf.label]
):
kernels[leaf.label] = leaf.undamped
else:
logger.info("Mixture update: rebuild %s undamped Raman model", leaf.label)
return TranslationReuse(
problem.transform,
problem.initial,
_same_operator_function(
source, updated, old, new, problem.linear.phi_expansion
),
_same_operator_function(
source, updated, old, new, problem.responses.prefactor_expansion
),
kernels,
transverse_of(problem.route),
)
def _undamped_model_key(response: RamanResponse) -> object:
"""Describe only the inputs to the undamped Raman samples."""
models = []
for term in response.tensor_terms:
model = term.model
record = serialise(model)
if isinstance(model, (DampedOscillator, RotationalLines)):
assert isinstance(record, dict)
record.pop("dephasing", None)
models.append((term.contraction, record))
return models