Source code for solprop.backends.export

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

"""Destination-based export of a session's field (SEP 47 section 5.4).

The output layer owns the definition of what a saved field means: true-power modal
amplitudes, or a spatial route's field measure, in the optics convention on disk
(ADR-017; ``docs/dev/conventions.md``). It states that definition once, as an
:class:`ExportRecipe`, and a session applies it while filling a destination: the
reference session with :func:`apply_recipe`, the native session in its own fused pass.
The definition does not move; only where it is evaluated does.

Every conversion step is exact or is the one multiplication today's two-step path
makes: a real square-root weight times the amplitude, then a conjugation and a
multiplication by ``(-1)**k``. Applied in that order, the fused pass is bitwise equal
to :func:`solprop.fourier.power_amplitude` followed by
:func:`solprop.fourier.spectrum_to_optics`, so lossless storage stays exact.

A destination is either an array the caller supplies -- a preallocated store row --
or a newly owned array the session allocates. Either way the result is detached: it is
never a view of a live workspace, and the session never writes to it again.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import TYPE_CHECKING

import numpy as np

from solprop.exceptions import BackendError, GridError

if TYPE_CHECKING:
    from jaxtyping import Complex, Float

__all__ = ["ExportRecipe", "apply_recipe"]


[docs] @dataclass(frozen=True) class ExportRecipe: """What conversion a field export applies on its way to a destination. Attributes ---------- power : bool Multiply modal amplitudes by the square root of the route's true-power weight at the exported position (``fourier.power_amplitude``). False on spatial routes, whose field measure is already the stored quantity. optics : bool Convert from the internal FFT convention to the optics convention about the window centre, ``(-1)**k conj(.)`` (``fourier.spectrum_to_optics``). True for a plane store; False for a consumer that works in the internal convention, such as a plane observer or a terminal checkpoint record. Examples -------- >>> from solprop.backends.export import ExportRecipe >>> ExportRecipe(power=True, optics=False) ExportRecipe(power=True, optics=False) """ power: bool optics: bool
[docs] def apply_recipe( state: Complex[np.ndarray, "n_modes n_pol n_omega"], recipe: ExportRecipe, *, weight: Float[np.ndarray, "n_modes n_pol n_omega"] | None, out: Complex[np.ndarray, "n_modes n_pol n_omega"] | None = None, ) -> Complex[np.ndarray, "n_modes n_pol n_omega"]: """Fill a destination with a field converted by a recipe, in one pass. The reference implementation of SEP 47's export. `state` is only read; the result is `out` when given, and otherwise a new array, so it never aliases `state`. Parameters ---------- state : numpy.ndarray The committed field, complex128, internal FFT convention, internal amplitude units, shape ``(n_modes, n_pol, n_omega)``. recipe : ExportRecipe The conversion. weight : numpy.ndarray or None The true-power weight at the field's position, positive and finite, the shape of `state`; required when ``recipe.power`` and ignored otherwise. out : numpy.ndarray or None, optional The destination, complex128, C-contiguous, the shape of `state`, not overlapping it; a new array by default. `state` itself converts in place, for a session that owns the only reference to it; each step is elementwise, so the result is the same bits. Returns ------- numpy.ndarray The converted field: `out` when given. Raises ------ BackendError If `out` has the wrong shape, dtype or layout, or overlaps `state`. GridError If a weight is required and missing, or not positive and finite. Examples -------- >>> import numpy as np >>> from solprop.backends.export import ExportRecipe, apply_recipe >>> state = np.array([[[1 + 1j, 2 - 1j]]]) >>> apply_recipe(state, ExportRecipe(power=True, optics=True), ... weight=np.full((1, 1, 2), 4.0)).tolist() [[[(2-2j), (-4-2j)]]] """ if out is None: out = np.empty_like(state, dtype=np.complex128, order="C") elif out is not state: _check_destination(state, out) if recipe.power: if weight is None: msg = "a true-power export needs the route's weight at its position" raise GridError(msg) if not np.all(np.isfinite(weight) & (weight > 0)): msg = "power weights must be positive and finite" raise GridError(msg) if not np.all(weight == 1.0): np.multiply(state, np.sqrt(weight), out=out) elif out is not state: np.copyto(out, state) elif out is not state: np.copyto(out, state) if recipe.optics: shift = np.ones(state.shape[-1]) shift[1::2] = -1.0 np.conj(out, out=out) np.multiply(shift, out, out=out) return out
def _check_destination( state: Complex[np.ndarray, "n_modes n_pol n_omega"], out: Complex[np.ndarray, "n_modes n_pol n_omega"], ) -> None: """Refuse a destination that cannot hold an export of `state`. Parameters ---------- state : numpy.ndarray The field being exported. out : numpy.ndarray The proposed destination. Raises ------ BackendError Naming the mismatch. """ if out.shape != state.shape: msg = f"an export destination has shape {out.shape}, expected {state.shape}" raise BackendError(msg) if ( out.dtype != np.complex128 or not out.flags.c_contiguous or not out.flags.writeable ): msg = "an export destination must be writeable, C-contiguous complex128" raise BackendError(msg) if np.shares_memory(out, state): msg = "an export destination must not overlap the session's state" raise BackendError(msg)