# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The plasma passes: ionisation rates, populations and the plasma currents.
The field grid's plasma, the ``ionisation_rate``, ``plasma_scan`` and
``plasma_current`` stages of ``responses.response_order``: :func:`ionisation_rate` looks
the rate up on the field's magnitude, :func:`plasma_scan` integrates the ionised
fraction and the free current along t, and :func:`plasma_total_current` adds the
loss current; :func:`plasma_channel_fractions` and :func:`plasma_channels_current` are
the same for independent channels. :func:`held_plasma_spectrum` turns a current held
at the temporal collar into its polarisation spectrum (SEP 27).
:func:`plasma_current` and :func:`plasma_channels_polarisation` integrate to the
time-domain polarisation, the oracle form, and
:func:`plasma_integration_diagnostics` measures the running integral (SEP 18).
The envelope grid's plasma is cycle-averaged: :func:`envelope_sources` and
:func:`envelope_populations` split each sample's complex envelope into its
polarisation ellipse by an SVD, read the cycle moments of the rate
(:func:`solprop.translate.envelope_plasma.cycle_moments`) and integrate the exposure
by the trapezoid.
"""
from collections.abc import Sequence
import numpy as np
from jaxtyping import Bool, Complex, Float, Int
from solprop.exceptions import BackendError
from solprop.nonlinear.ionisation import RunningIntegral
from solprop.translate.envelope_plasma import (
CycleIntegralData,
EnvelopePlasmaAssembly,
cycle_moments,
)
from solprop.translate.ionisation import RateTable
from solprop.translate.responses import (
PlasmaChannel,
PlasmaCoefficients,
)
from solprop.translate.stage import StageScalars
__all__ = [
"envelope_populations",
"envelope_sources",
"held_plasma_spectrum",
"ionisation_rate",
"plasma_channel_fractions",
"plasma_channels_current",
"plasma_channels_polarisation",
"plasma_current",
"plasma_integration_diagnostics",
"plasma_integration_statistics",
"plasma_scan",
"plasma_total_current",
]
[docs]
def ionisation_rate(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
table: RateTable,
) -> Float[np.ndarray, "n_nodes_chunk n_to"]:
r"""Look the ionisation rate up on the magnitude of the field.
The ``intensity`` and ``ionisation_rate`` stages of the fused pass, together: the
magnitude is what the intensity stage forms and the only thing the rate needs. For
one component that is ``|E|``; for two it is ``hypot(E_x, E_y)`` rather than
``sqrt(E_x^2 + E_y^2)``, because the tunnelling exponent is tens to hundreds and
turns one unit in the last place of the magnitude into 1e-13 of the rate
(:meth:`solprop.nonlinear.responses.PlasmaResponse.evaluate` takes the same route).
The table is exactly zero below its ``field_min`` and holds its last value above
``field_max`` rather than extrapolating, which is what keeps the loss current of
:func:`plasma_current` finite and a diverged step from becoming an infinity.
Parameters
----------
field_t : numpy.ndarray
The real field at the chunk's nodes, shape ``(n_nodes_chunk, n_pol, n_to)``, in
V/m.
table : solprop.translate.ionisation.RateTable
The compiled rate, ``responses.plasma_coefficients.rate``.
Returns
-------
numpy.ndarray
The rate per atom in s^-1, shape ``(n_nodes_chunk, n_to)``, finite and
non-negative.
Examples
--------
>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.plasma import ionisation_rate
>>> from solprop.nonlinear.optmat_rates import OptmatRate
>>> from solprop.translate.ionisation import build_rate_table
>>> table = build_rate_table(OptmatRate("He", 800e-9), (2e9, 1e11), rtol=1e-4)
>>> field = np.array([[[5e10, 1e6]]])
>>> np.round(np.log10(ionisation_rate(field, table)[0, 0]), 3).item()
11.207
"""
return table(_magnitude(field_t))
[docs]
def plasma_scan(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
rate: Float[np.ndarray, "n_nodes_chunk n_to"],
coefficients: PlasmaCoefficients,
*,
preionisation: float,
dt: float,
integral: RunningIntegral | None = None,
) -> tuple[
Float[np.ndarray, "n_nodes_chunk n_to"],
Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
]:
r"""Integrate the ionised fraction and the free-electron current along t.
The ``plasma_scan`` stage: two of the three cumulative integrals the response
declares, which is why its domain is ``memory`` -- the value at one sample depends
on every earlier sample and on none of the later ones.
``f = 1 - (1 - f_0) exp(-int W dt)``, with the pre-ionised fraction **inside** the
exponential. Writing ``f_0 + 1 - exp(-int W dt)`` instead would let ``f`` exceed
one, make ``1 - f`` negative and stop ``df/dt`` being ``W (1 - f)``, so the loss
term would no longer pay exactly one ionisation potential per electron. Then
``J_free = (e^2/m_e) int f E dt``, the current of electrons already freed and still
being accelerated: what lowers the refractive index and blue-shifts the pulse.
Both integrals are the problem's running-integral rule (SEP 18), applied in the
argument order of :meth:`solprop.nonlinear.responses.PlasmaResponse.evaluate`, each
a vectorised cumulative sum (``scipy.integrate.cumulative_trapezoid``); this pass
and the oracle are the same computation, and other backends' scans are held to the
scan's rounding bound (SEP 25), not to its order. Under the band
rule the exposure is floored at zero, so the fraction stays in
``[preionisation, 1)`` and is non-decreasing to within the filter's undershoot. Here
the multipass form **is** the reference, and fusing the three sums into one
sequential sweep belongs to the native backend
(``docs/guide/media/nonlinear.md``).
Parameters
----------
field_t : numpy.ndarray
The real field at the chunk's nodes, shape ``(n_nodes_chunk, n_pol, n_to)``, in
V/m.
rate : numpy.ndarray
The ionisation rate from :func:`ionisation_rate`, s^-1, shape
``(n_nodes_chunk, n_to)``.
coefficients : solprop.translate.responses.PlasmaCoefficients
The compiled plasma group; only ``charge_mass_ratio`` is read here.
preionisation : float
The pre-ionised fraction at this position,
``coefficients.preionisation(z)``, in ``[0, 1]``.
dt : float
Sample spacing of the fine time grid, s, positive.
integral : solprop.nonlinear.ionisation.RunningIntegral or None, optional
The running-integral rule, ``responses.plasma_integral``; ``None`` is the
trapezoid.
Returns
-------
fraction : numpy.ndarray
The fraction ionised, shape ``(n_nodes_chunk, n_to)``, in
``[preionisation, 1]`` and non-decreasing in time (under the band rule, to
within the filter's undershoot).
free_current : numpy.ndarray
``J_free`` per unit density, shape ``(n_nodes_chunk, n_pol, n_to)``, in
C/(m^2 s) per m^-3.
Examples
--------
>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.plasma import plasma_scan
>>> from solprop.nonlinear.optmat_rates import OptmatRate
>>> from solprop.nonlinear.responses import PlasmaResponse
>>> from solprop.translate.responses import plasma_coefficients
>>> compiled = plasma_coefficients(
... PlasmaResponse("Ar", OptmatRate("Ar", 800e-9)), (1e9, 1e11), z_max=1.0
... )
>>> field = np.zeros((1, 1, 4))
>>> fraction, current = plasma_scan(
... field, np.zeros((1, 4)), compiled, preionisation=0.25, dt=1e-16
... )
>>> fraction.tolist(), bool(np.all(current == 0.0))
([[0.25, 0.25, 0.25, 0.25]], True)
"""
rule = _rule(integral)
exposure = rule.floor(rule.integrate(rate, dt))
fraction = 1.0 - (1.0 - preionisation) * np.exp(-exposure)
integrand = fraction[..., np.newaxis, :] * coefficients.charge_mass_ratio * field_t
free_current = rule.integrate(integrand, dt)
return fraction, free_current
def _rule(integral: RunningIntegral | None) -> RunningIntegral:
"""Return the running-integral rule a plasma pass uses.
- ``integral``: the problem's rule, or ``None`` for the trapezoid.
"""
return RunningIntegral.trapezoid() if integral is None else integral
[docs]
def plasma_current(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
rate: Float[np.ndarray, "n_nodes_chunk n_to"],
fraction: Float[np.ndarray, "n_nodes_chunk n_to"],
free_current: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
coefficients: PlasmaCoefficients,
*,
density: float,
dt: float,
integral: RunningIntegral | None = None,
) -> Float[np.ndarray, "n_nodes_chunk n_pol n_to"]:
r"""Add the ionisation loss to the free current and integrate to a polarisation.
The ``plasma_current`` stage, and the third cumulative integral.
``J_loss = I_p W (1 - f) E / |E|^2`` is added pointwise; its form is fixed by
``E . J_loss = I_p W (1 - f) = I_p df/dt``, so the field pays exactly one ionisation
potential for every electron it frees. For one component it is ``I_p W (1-f)/E``,
sign and all; for two it is that magnitude **directed along the field**, which is
what makes a linearly polarised pulse give the scalar answer rotated. The
polarisation is ``P = rho int (J_free + J_loss) dt``.
The division is written with a ``where`` mask rather than a branch, as the oracle
writes it, so it never happens at a sample where the rate or the field vanishes: the
term is finite only because the rate is **exactly** zero below threshold, which is
what :class:`solprop.translate.ionisation.RateTable` guarantees below its
``field_min``; a clipped but non-zero rate would divide by a tiny ``|E|^2``.
Parameters
----------
field_t : numpy.ndarray
The real field at the chunk's nodes, shape ``(n_nodes_chunk, n_pol, n_to)``, in
V/m.
rate : numpy.ndarray
The ionisation rate from :func:`ionisation_rate`, s^-1, shape
``(n_nodes_chunk, n_to)``.
fraction : numpy.ndarray
The fraction ionised from :func:`plasma_scan`, shape
``(n_nodes_chunk, n_to)``.
free_current : numpy.ndarray
``J_free`` from :func:`plasma_scan`, shape ``(n_nodes_chunk, n_pol, n_to)``.
coefficients : solprop.translate.responses.PlasmaCoefficients
The compiled plasma group; only ``ionisation_potential`` is read here.
density : float
The density path at this position, ``responses.density(z)``, in m^-3,
non-negative. The currents are per atom; this is what turns them into a
polarisation.
dt : float
Sample spacing of the fine time grid, s, positive.
integral : solprop.nonlinear.ionisation.RunningIntegral or None, optional
The running-integral rule, ``responses.plasma_integral``; ``None`` is the
trapezoid.
Returns
-------
numpy.ndarray
The plasma polarisation in C/m^2, shape ``(n_nodes_chunk, n_pol, n_to)``.
Examples
--------
>>> import numpy as np
>>> from solprop.backends.numpy_ref.passes.plasma import plasma_current
>>> from solprop.nonlinear.optmat_rates import OptmatRate
>>> from solprop.nonlinear.responses import PlasmaResponse
>>> from solprop.translate.responses import plasma_coefficients
>>> compiled = plasma_coefficients(
... PlasmaResponse("Ar", OptmatRate("Ar", 800e-9)), (1e9, 1e11), z_max=1.0
... )
>>> zeros = np.zeros((1, 1, 4))
>>> flat = np.zeros((1, 4))
>>> plasma_current(
... zeros, flat, flat, zeros, compiled, density=1e25, dt=1e-16
... ).tolist()
[[[0.0, 0.0, 0.0, 0.0]]]
"""
current = plasma_total_current(field_t, rate, fraction, free_current, coefficients)
return density * _rule(integral).integrate(current, dt)
[docs]
def plasma_total_current(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
rate: Float[np.ndarray, "n_nodes_chunk n_to"],
fraction: Float[np.ndarray, "n_nodes_chunk n_to"],
free_current: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
coefficients: PlasmaCoefficients,
) -> Float[np.ndarray, "n_nodes_chunk n_pol n_to"]:
"""Add the guarded loss current to the free current, per unit density.
``J_free + I_p W (1 - f) E / |E|^2``, the integrand of :func:`plasma_current` and
what a stage holds at the collar (SEP 27); the guard is the one
:func:`plasma_current` describes.
Parameters
----------
field_t : numpy.ndarray
The real field at the chunk's nodes, shape ``(n_nodes_chunk, n_pol, n_to)``,
in V/m.
rate : numpy.ndarray
The ionisation rate from :func:`ionisation_rate`, s^-1, shape
``(n_nodes_chunk, n_to)``.
fraction : numpy.ndarray
The fraction ionised from :func:`plasma_scan`, shape ``(n_nodes_chunk, n_to)``.
free_current : numpy.ndarray
``J_free`` from :func:`plasma_scan`, shape ``(n_nodes_chunk, n_pol, n_to)``.
coefficients : solprop.translate.responses.PlasmaCoefficients
The compiled plasma group; only ``ionisation_potential`` is read here.
Returns
-------
numpy.ndarray
The total current per unit number density, in A m, with the field's shape.
"""
# The squared magnitude rather than the field itself: it is the divisor the guard
# has to test, and it underflows to zero below about 1e-162 V/m.
squared = _magnitude(field_t) ** 2
scale = np.zeros_like(squared)
np.divide(
coefficients.ionisation_potential * rate * (1.0 - fraction),
squared,
out=scale,
where=(rate > 0.0) & (squared > 0.0),
)
return free_current + scale[..., np.newaxis, :] * field_t
[docs]
def plasma_channel_fractions(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
channels: tuple[PlasmaChannel, ...],
preionisation: tuple[float, ...],
dt: float,
integral: RunningIntegral | None = None,
) -> tuple[
Float[np.ndarray, "n_channels n_nodes_chunk n_to"],
Float[np.ndarray, "n_channels n_nodes_chunk n_to"],
]:
"""Evaluate independent exposure scans in channel order.
Parameters
----------
field_t : numpy.ndarray
Real node fields in V/m, shape (n_nodes_chunk, n_pol, n_to).
channels : tuple of PlasmaChannel
The independent rate tables and population metadata.
preionisation : tuple of float
Initial fractions, in channel order, in [0, 1].
dt : float
Fine-grid sample spacing in s.
integral : solprop.nonlinear.ionisation.RunningIntegral or None, optional
The running-integral rule; ``None`` is the trapezoid.
Returns
-------
rates : numpy.ndarray
Instantaneous rates in s^-1, shape (n_channels, n_nodes_chunk, n_to).
fractions : numpy.ndarray
Ionised fractions with the same shape, dimensionless.
Raises
------
BackendError
If the channel scalars do not match their declared count.
"""
if not channels or len(channels) != len(preionisation):
raise BackendError("plasma channels require one initial fraction each")
magnitude = _magnitude(field_t)
rates = np.stack([channel.rate(magnitude) for channel in channels])
fractions = np.empty_like(rates)
rule = _rule(integral)
for index, initial in enumerate(preionisation):
exposure = rule.floor(rule.integrate(rates[index], dt))
fractions[index] = 1.0 - (1.0 - initial) * np.exp(-exposure)
return rates, fractions
[docs]
def plasma_channels_polarisation(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
channels: tuple[PlasmaChannel, ...],
densities: tuple[float, ...],
preionisation: tuple[float, ...],
dt: float,
*,
integral: RunningIntegral | None = None,
) -> Float[np.ndarray, "n_nodes_chunk n_pol n_to"]:
r"""Sum channel weights before the two shared current integrals.
Each fraction has its own exposure scan (:func:`plasma_channel_fractions`). The
free-current weight is ``sum rho_c f_c e_c^2/m_c`` (times each channel's electrons
per event); the loss numerator is ``sum rho_c I_p,c W_c (1-f_c)``, divided by
``|E|^2`` and directed along the field as in :func:`plasma_current`. The densities
are inside the sums, where the one-channel pass keeps its density outside the
integrals.
Parameters
----------
field_t : numpy.ndarray
Real node fields in V/m, shape (n_nodes_chunk, n_pol, n_to).
channels : tuple of PlasmaChannel
Ordered independent channel coefficients.
densities : tuple of float
Number density of each population in m^-3.
preionisation : tuple of float
Initial fraction of each population, dimensionless in [0, 1].
dt : float
Fine-grid sample spacing in s.
integral : solprop.nonlinear.ionisation.RunningIntegral or None, optional
The running-integral rule shared by every channel; ``None`` is the trapezoid.
Returns
-------
numpy.ndarray
Plasma polarisation in C/m², with the field shape.
Raises
------
BackendError
If there is not one density per channel.
"""
return _rule(integral).integrate(
plasma_channels_current(
field_t, channels, densities, preionisation, dt, integral
),
dt,
)
[docs]
def plasma_channels_current( # noqa: PLR0917 - the scan's positional signature
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
channels: tuple[PlasmaChannel, ...],
densities: tuple[float, ...],
preionisation: tuple[float, ...],
dt: float,
integral: RunningIntegral | None = None,
) -> Float[np.ndarray, "n_nodes_chunk n_pol n_to"]:
r"""Return every channel's free and loss current, summed, before the last integral.
The integrand of :func:`plasma_channels_polarisation`, and what a stage holds at
the collar: the free current is the one shared integral of the weighted field, the
loss current is pointwise.
Parameters
----------
field_t : numpy.ndarray
Real node fields in V/m, shape ``(n_nodes_chunk, n_pol, n_to)``.
channels : tuple of PlasmaChannel
Ordered independent channel coefficients.
densities : tuple of float
Number density of each population in m^-3.
preionisation : tuple of float
Initial fraction of each population, dimensionless in ``[0, 1]``.
dt : float
Fine-grid sample spacing in s.
integral : solprop.nonlinear.ionisation.RunningIntegral or None, optional
The running-integral rule shared by every channel; ``None`` is the trapezoid.
Returns
-------
numpy.ndarray
The total plasma current density in A/m^2, with the field's shape.
Raises
------
BackendError
If there is not one density per channel.
"""
if len(densities) != len(channels):
raise BackendError("plasma channels require one density each")
rule = _rule(integral)
rates, fractions = plasma_channel_fractions(
field_t, channels, preionisation, dt, rule
)
weight = np.zeros_like(rates[0])
work = np.zeros_like(weight)
for channel, density, rate, fraction in zip(
channels, densities, rates, fractions, strict=True
):
weight += (
density * fraction * channel.charge_mass_ratio * channel.electrons_per_event
)
work += density * channel.ionisation_potential * rate * (1.0 - fraction)
free = rule.integrate(weight[:, None, :] * field_t, dt)
squared = _magnitude(field_t) ** 2
guard = np.zeros_like(work)
np.divide(work, squared, out=guard, where=squared > 0.0)
loss = guard[:, None, :] * field_t
return free + loss
[docs]
def plasma_integration_diagnostics(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
channels: Sequence[PlasmaCoefficients],
preionisation: tuple[float, ...],
dt: float,
integral: RunningIntegral | None = None,
) -> Float[np.ndarray, " 6"]:
"""Return the parts of the column's integration diagnostics (SEP 18).
For every channel and node: the exposure ``S`` as the rule forms it, before the
floor, and its increments; the fraction; the work the loss current pays per
ionisation potential, ``int W (1 - f) dt`` by the trapezoid of the raw rate; the
electrons that freed, ``f_end - f_0``; and the free-current integrand ``|f E|``.
Every part is a maximum over nodes and channels, so chunks combine by taking the
largest of each, and each ratio is normalised by the most-ionised node rather than
node by node: a node the field barely ionises, whose rate is one sampled spike,
would otherwise report the filter's full undershoot on a rate at the level of
rounding (:func:`plasma_integration_statistics` forms the ratios).
Parameters
----------
field_t : numpy.ndarray
Real node fields in V/m, shape ``(n_nodes_chunk, n_pol, n_to)``.
channels : sequence of PlasmaCoefficients
The channels' compiled coefficients, each with its rate table.
preionisation : tuple of float
Each channel's initial fraction at this plane.
dt : float
Fine-grid sample spacing in s.
integral : solprop.nonlinear.ionisation.RunningIntegral or None, optional
The running-integral rule; ``None`` is the trapezoid.
Returns
-------
numpy.ndarray
The largest exposure dip ``-min dS`` and rise ``max dS``; the largest
``|paid - freed|`` and ``freed``; the largest ``|f E|`` in the first ``2K``
samples and anywhere. Dimensionless but for the last two, in V/m.
"""
rule = _rule(integral)
reach = 2 * rule.half_width
magnitude = _magnitude(field_t)
parts = np.zeros(6)
for channel, initial in zip(channels, preionisation, strict=True):
rate = channel.rate(magnitude)
exposure = rule.integrate(rate, dt)
steps = np.diff(exposure, axis=-1)
fraction = 1.0 - (1.0 - initial) * np.exp(-rule.floor(exposure))
paid = np.trapezoid(rate * (1.0 - fraction), dx=dt, axis=-1)
freed = fraction[..., -1] - fraction[..., 0]
integrand = np.abs(fraction[..., np.newaxis, :] * field_t)
early = float(np.max(integrand[..., :reach])) if reach else 0.0
parts = np.maximum(
parts,
[
max(-float(np.min(steps)), 0.0),
float(np.max(steps)),
float(np.max(np.abs(paid - freed))),
float(np.max(freed)),
early,
float(np.max(integrand)),
],
)
return parts
[docs]
def plasma_integration_statistics(
parts: Float[np.ndarray, " 6"],
) -> tuple[float, float, float]:
"""Form the three diagnostics from :func:`plasma_integration_diagnostics`'s parts.
Parameters
----------
parts : numpy.ndarray
The six maxima, combined over every chunk of nodes.
Returns
-------
tuple of float
The undershoot ``max(-dS) / max(dS)``, the work defect
``max |paid - freed| / max freed`` and the boundary level, each zero where
its denominator is.
"""
dip, rise, defect, freed, early, peak = (float(part) for part in parts)
return (
dip / rise if rise > 0.0 else 0.0,
defect / freed if freed > 0.0 else 0.0,
early / peak if peak > 0.0 else 0.0,
)
[docs]
def held_plasma_spectrum(
gated: Float[np.ndarray, "... n_to"],
edge: Float[np.ndarray, "... n_to"],
omega: Float[np.ndarray, " n_omega"],
crop_index: Int[np.ndarray, " n_omega"],
active: Bool[np.ndarray, " n_omega"],
) -> Complex[np.ndarray, "... n_omega"]:
r"""Transform a current held at the temporal collar (SEP 27 section 4.4).
Form ``DFT[g J]/(i omega) - DFT[g' J]/(i omega)^2`` only on active bins.
Projection can precede or follow this linear map; crop and amplitude factors
belong to the route. No running integral or numerical derivative enters it.
Parameters
----------
gated, edge : numpy.ndarray
Sampled ``g J`` and ``g' J``, in A/m^2 and A/(m^2 s), with time last.
omega : numpy.ndarray
Coarse angular frequencies in rad/s, shape ``(n_omega,)``.
crop_index : numpy.ndarray
Coarse positions in the fine half-spectrum, shape ``(n_omega,)``.
active : numpy.ndarray
Active frequency mask, shape ``(n_omega,)``; all selected frequencies positive.
Returns
-------
numpy.ndarray
Polarisation-equivalent spectrum in raw DFT units, with inactive bins zero.
"""
current = np.fft.rfft(gated, axis=-1)[..., crop_index]
derivative = np.fft.rfft(edge, axis=-1)[..., crop_index]
result = np.zeros_like(current)
q = 1j * omega[active]
result[..., active] = current[..., active] / q - derivative[..., active] / q**2
return result
def _magnitude(
field_t: Float[np.ndarray, "n_nodes_chunk n_pol n_to"],
) -> Float[np.ndarray, "n_nodes_chunk n_to"]:
"""Return the field magnitude the ionisation rate and the loss term take.
- Returns: ``|E|`` in V/m, shape ``(n_nodes_chunk, n_to)``.
"""
if field_t.shape[-2] == 1:
return np.abs(field_t[..., 0, :])
return np.hypot(field_t[..., 0, :], field_t[..., 1, :])
[docs]
def envelope_sources(
field_t: Complex[np.ndarray, "n_nodes n_pol n_to"],
assembly: EnvelopePlasmaAssembly,
scalars: StageScalars,
dt: float,
window: Float[np.ndarray, " n_to"],
) -> tuple[
Complex[np.ndarray, "n_nodes n_pol n_to"],
Complex[np.ndarray, "n_nodes n_pol n_to"],
]:
"""Form two windowed sources from independently recomputed channel populations.
Parameters
----------
field_t : numpy.ndarray
Physical complex V/m envelope, shape ``(n_nodes, n_pol, n_to)``.
assembly : EnvelopePlasmaAssembly
Labelled channels and validated cycle data.
scalars : StageScalars
Density and pre-ionisation at this RHS position in channel order.
dt : float
Fine time spacing in s.
window : numpy.ndarray
Material-source collar, shape ``(n_to,)``.
Returns
-------
tuple of numpy.ndarray
Drude drive in A m^-2 s^-1 and loss current in A m^-2, each with the
field's shape. Projection and temporal FFT follow this function.
"""
drive = np.zeros_like(field_t)
loss = np.zeros_like(field_t)
for channel, density, initial in zip(
assembly.channels,
scalars.plasma_densities,
scalars.plasma_preionisation,
strict=True,
):
for node, field in enumerate(field_t):
rate, current = _cycle_quantities(field, channel.cycle, loss=True)
fraction, survival = _population(rate, initial, dt)
drive[node] += (channel.charge_mass_ratio * density * fraction) * field
loss[node] += (channel.ionisation_potential * density * survival) * current
return drive * window, loss * window
def _cycle_quantities(
field: Complex[np.ndarray, "n_pol n_to"], cycle: CycleIntegralData, *, loss: bool
) -> tuple[Float[np.ndarray, " n_to"], Complex[np.ndarray, "n_pol n_to"]]:
"""Evaluate rate and optional directional loss by independent SVD axes.
- ``field``: physical V/m envelope, shape (n_pol, n_to).
- Returns: rate in s^-1 and loss moment per unit ionisation work, with shapes
(n_to,) and (n_pol, n_to).
"""
rate = np.zeros(field.shape[1])
current = np.zeros_like(field)
for sample in range(field.shape[1]):
a = field[:, sample]
scale = float(np.max(np.abs(a)))
if scale == 0:
continue
matrix = np.column_stack((np.real(a) / scale, np.imag(a) / scale))
left, singular, right = np.linalg.svd(matrix, full_matrices=False)
major = float(singular[0]) * scale
ratio = (
0.0 if len(singular) == 1 else min(1.0, float(singular[1] / singular[0]))
)
moments = cycle_moments(major, ratio, cycle)
rate[sample] = moments[0] + ratio**2 * moments[1]
if not loss:
continue
current[:, sample] = (
(2 * (moments[0] / major)) * left[:, 0] * (right[0, 0] + 1j * right[0, 1])
)
if len(singular) == 2:
current[:, sample] += (
(2 * (ratio * moments[1] / major))
* left[:, 1]
* (right[1, 0] + 1j * right[1, 1])
)
return rate, current
def _population(
rate: Float[np.ndarray, " n_to"], initial: float, dt: float
) -> tuple[Float[np.ndarray, " n_to"], Float[np.ndarray, " n_to"]]:
"""Retain survival separately from a cancellation-free population scan.
- ``rate``: Cycle-averaged rates in s^-1, shape (n_to,).
- ``initial``: initial ionised fraction in [0, 1].
- ``dt``: fine time spacing in s.
- Returns: ionised fraction and surviving neutral fraction, each shape (n_to,).
"""
with np.errstate(over="ignore"):
increments = (0.5 * rate[:-1] + 0.5 * rate[1:]) * dt
exposure = np.concatenate((np.zeros(1), np.cumsum(increments)))
survival = (1 - initial) * np.exp(-exposure)
fraction = initial + (1 - initial) * -np.expm1(-exposure)
return fraction, survival
[docs]
def envelope_populations(
field_t: Complex[np.ndarray, "n_nodes n_pol n_to"],
assembly: EnvelopePlasmaAssembly,
initials: tuple[float, ...],
dt: float,
) -> tuple[
Float[np.ndarray, "n_channels n_nodes"], Float[np.ndarray, "n_channels n_nodes"]
]:
"""Recompute each node's final population and peak cycle-averaged rate.
Parameters
----------
field_t : numpy.ndarray
Physical V/m envelopes, shape (n_nodes, n_pol, n_to).
assembly : EnvelopePlasmaAssembly
Compiled channels in population order.
initials : tuple of float
Initial fractions at this position in channel order.
dt : float
Fine time spacing in s.
Returns
-------
tuple of numpy.ndarray
Final fractions and peak cycle-averaged rates in s^-1, both shaped
(n_channels, n_nodes). Every call scans the supplied field afresh.
"""
fractions = np.empty((len(assembly.channels), len(field_t)))
peaks = np.empty_like(fractions)
for index, (channel, initial) in enumerate(
zip(assembly.channels, initials, strict=True)
):
for node, field in enumerate(field_t):
rate, _ = _cycle_quantities(field, channel.cycle, loss=False)
fraction, _ = _population(rate, initial, dt)
fractions[index, node] = fraction[-1]
peaks[index, node] = np.max(rate)
return fractions, peaks