Source code for solprop.translate.admission

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

"""What the general modal route and the coupled flow execute, checked once.

:func:`check_general_route` refuses, by name, each general modal or coupled-flow problem
solprop does not run, and :func:`check_leaf_types` a general-modal leaf that is not its
record type. Both backends execute the same combinations of these leaves, so the list
is part of the problem's validation
(:meth:`solprop.translate.problem.PropagationProblem.validate`, which
:func:`solprop.translate.problem.validate_run` runs where a backend is built): each
refusal has one raise site, before any buffer is allocated. The leaves' consistency
with the state -- channel and component counts, axes, extents -- is ``validate``'s own
and runs first. A problem can be assembled by something other than
:func:`solprop.translate.assembly.assemble`, so nothing here relies on the assembly
having refused it already.
"""

from typing import TYPE_CHECKING

import numpy as np

from solprop.exceptions import TranslationError
from solprop.modes.tables import DEFAULT_GRAM_ATOL
from solprop.translate.coupled import CoupledFlowTables, ModalMetricTables
from solprop.translate.general import (
    MAX_DENSE_METRIC_DEPARTURE,
    check_regional_responses,
    metric_departure,
)
from solprop.translate.linop import LinearOperator
from solprop.translate.modal_tables import ModalTransformTables
from solprop.translate.responses import RegionalResponseTables

if TYPE_CHECKING:
    from solprop.translate.problem import PropagationProblem

__all__ = ["check_general_route", "check_leaf_types"]


[docs] def check_general_route(problem: "PropagationProblem") -> None: """Refuse, by name, each general modal or coupled-flow problem solprop does not run. The coupled flow first: a metric or a table beside it is this route's refusal to make, not the general route's. Then the general modal route: the tables' own execution maps, an identity metric or the dense metric of a declared unitary change of basis of one, the constant unit power weight, no channel response beside the route's own, per-region responses of a known model, and moving maps only beside the flow that carries their connection. Its field grid is the leaves' own structure's to require: a leaf's increasing frequency axis is ``grids.omega``, which an envelope grid's FFT-ordered axis is not. A problem carrying none of the general-modal leaves passes untouched. Parameters ---------- problem : solprop.translate.problem.PropagationProblem The problem to check, its leaves consistent with its state. Raises ------ TranslationError Naming the leaf, or the part of the problem around it, that is not executed. Examples -------- >>> from solprop.driver import Simulation >>> from solprop.translate.admission import check_general_route >>> simulation = Simulation.from_gnlse( ... 0.11, 0.01, [0.0, 0.0, -1.183e-26], wavelength=835e-9, ... wavelength_limits=(500e-9, 2e-6), trange=1e-12, ... width=100e-15, peak_power=9.8, shape="sech", ... ) >>> check_general_route(simulation.translate()) is None True """ flow = problem.linear.coupled_flow if flow is not None: _check_flow_representation(flow) _check_flow_problem(problem, flow) _check_modal_route(problem)
[docs] def check_leaf_types(problem: "PropagationProblem") -> None: """Refuse a general-modal leaf that is not its record type, by name. The first of the leaves' consistency checks (:meth:`~solprop.translate.problem.PropagationProblem.validate`), so that a hand-built problem holding something else there meets a named refusal rather than an attribute error further in. Parameters ---------- problem : solprop.translate.problem.PropagationProblem The problem to check. Raises ------ TranslationError Naming the leaf, the type it holds and the type it must be. """ for name, leaf, kind in ( ( "transform.modal_tables", problem.transform.modal_tables, ModalTransformTables, ), ("linear.modal_metric", problem.linear.modal_metric, ModalMetricTables), ("linear.coupled_flow", problem.linear.coupled_flow, CoupledFlowTables), ( "responses.regional_responses", problem.responses.regional_responses, RegionalResponseTables, ), ): if leaf is not None and not isinstance(leaf, kind): msg = f"{name} is a {type(leaf).__name__}, not a {kind.__name__}" raise TranslationError(msg)
def _check_flow_representation(flow: CoupledFlowTables) -> None: """Refuse a coupled flow whose representation no backend executes.""" methods = set(flow.section_methods) frozen = methods == {"frozen_residual"} if flow.section_methods != ("constant_schur",) and not frozen: msg = ( "solprop executes one constant section by a Schur matrix-function " "action, or every section of a varying flow as 'frozen_residual', and this " f"flow declares {sorted(methods)} over " f"{len(flow.section_methods)} section(s): 'diagonal' is the existing " "cumulative flow and needs no leaf, and a constant-Schur section beside " "any other is not one a single held decomposition is built for" ) raise TranslationError(msg) if flow.representation != "dense": msg = ( "solprop executes the dense generator of a coupled flow and this one " f"is {flow.representation!r}: a factored generator is reconstructed by no " "kernel" ) raise TranslationError(msg) assert flow.generator is not None if not frozen and flow.generator.shape[1] != 1: msg = ( "solprop executes a constant-Schur coupled flow whose generator is " f"constant across its section, and this one carries " f"{flow.generator.shape[1]} Chebyshev degrees along z: a generator that " "varies inside its section is a 'frozen_residual' flow, which declares " "the residual its variation becomes" ) raise TranslationError(msg) if not frozen and flow.connection is not None: msg = ( "solprop executes no taper connection beside a constant section: " "linear.coupled_flow.connection is the moving-basis term of a taper and " "belongs to a 'frozen_residual' flow, whose explicit residual carries it" ) raise TranslationError(msg) if not frozen and float(np.max(flow.residual_norm_bound)) > 0.0: msg = ( "solprop executes a constant-Schur coupled flow with no explicit " f"residual, and this one declares up to " f"{float(np.max(flow.residual_norm_bound)):.4g} 1/m: a section whose " "generator varies inside it is a 'frozen_residual' flow" ) raise TranslationError(msg) def _check_flow_problem(problem: "PropagationProblem", flow: CoupledFlowTables) -> None: """Refuse a problem whose surroundings the coupled flow cannot be executed in. The cumulative diagonal ``Phi`` multiplies the flow action, which is only the same equation when the two **commute**, so ``Phi`` must be a multiple of the identity in channels; a shot-noise draw kept apart is transported by the unitary phase of a diagonal flow, which a nonunitary coupled flow is not; the flux of a condensed boundary block is the square-root model's, whose positivity is not established, so no explicit metric may sit beside one on the mode-set route; and the block is **scalar**: the action contracts the channel axis alone, so the state carries one polarisation. The TE/TM wall block (``CoherentWall(impedance="te_tm")``) is scalar in this sense too: its families are channels. The **transform** may resolve two transverse components, since the synthesis is read by the responses alone. """ _, n_pol, _ = problem.shape if n_pol != 1: msg = ( "solprop executes a coupled flow only for a scalar state, and this " f"problem's state carries n_pol = {n_pol} polarisation components (the " "product route): the flow's action contracts the channel axis alone, so " "a scalar block beside a state with two polarisation components would be " "applied to each as though it described both. " "CoherentWall(impedance='te_tm') names the wall's TE and TM impedances, " "not the state's polarisation axis: its families are channels, one " "component each" ) raise TranslationError(msg) linear = problem.linear constant = flow.section_methods == ("constant_schur",) if constant and ( linear.phi_representation != "constant" or linear.phi_constant is None ): msg = ( "solprop executes a constant-Schur coupled flow only beside the exact " f"constant representation of Phi, and this problem's is " f"{linear.phi_representation!r}: a varying carrier belongs to a " "'frozen_residual' flow" ) raise TranslationError(msg) if not _mode_independent(linear): msg = ( "solprop executes a coupled flow only beside a mode-independent Phi: " "the flow action and the cumulative diagonal are applied as a product, " "which is the same equation only when they commute, and a channel-" "dependent diagonal does not commute with a coupled block" ) raise TranslationError(msg) if not constant and not problem.device_ready: msg = ( "solprop executes a frozen-residual coupled flow only beside a Phi " "that is a weighted sum of fixed terms, and this problem's took the z " "table: the flow's own stage weights and the carrier's must come from " "one stage bundle, and the table has no such form " "(docs/dev/kernel-contract.md section 1)" ) raise TranslationError(msg) # The input model's draw was added to the state when it was loaded, so the flow # carries it as part of the field (SEP 37 section 6); only the modified model keeps # a draw apart that a flow would have to transport. if problem.initial.noise_model == "modified": msg = ( "solprop executes no 'modified' noise model beside a coupled flow: " "its one-photon-per-bin draw is advanced by the unitary phase of a " "diagonal flow, and its transport through a nonunitary coupled flow is " "not measured in this package; the 'input' model is admitted" ) raise TranslationError(msg) if linear.modal_metric is not None and problem.transform.modal_tables is None: # The coherent wall's own flux model: a condensed boundary block has no bound # reciprocal basis. A general modal guide's metric is the Gram of its own # sampled, power-orthonormal basis, and the coupled block there a declared # unitary rotation of it, which leaves the Gram's spectrum where it was; # `transform.modal_tables` tells the two apart. msg = ( "solprop executes no explicit metric beside a coupled flow on the " "mode-set route: the flux of a condensed boundary block is the " "square-root model's, whose positivity is not established. A general " "modal guide carries " "transform.modal_tables and its metric is its own sampled basis Gram, " "which this problem does not" ) raise TranslationError(msg) def _mode_independent(linear: LinearOperator) -> bool: """Return whether the cumulative ``Phi`` is a multiple of the identity in channels. That, and not constancy, is what the product ``exp(dPhi) exp(dz G_s)`` needs. Every representation is checked in its own terms -- the exact constant array, the expansion's fixed terms, or the table's coefficients -- because a varying guide takes whichever of them its declared parameters allow. """ held: list[np.ndarray] = [] if linear.phi_constant is not None: held.append(linear.phi_constant) if linear.phi_expansion is not None: held.append(linear.phi_expansion.terms) if linear.phi_coefficients is not None: held.append(linear.phi_coefficients) return all( np.array_equal( block, np.broadcast_to(np.take(block, [0], axis=-3), block.shape), ) for block in held ) def _check_modal_route(problem: "PropagationProblem") -> None: """Refuse every general modal problem solprop does not execute. The route is one combination: a field grid (which the leaves' frequency axes already require), the tables' own execution maps, an **identity** metric -- the Poynting-normalised orthogonal basis the Gram gate certifies -- or the dense metric of a declared unitary change of basis of one, the constant unit power weight of a true-power amplitude, and the route's own responses. A channel response beside them is refused, because the route's source replaces the channel node pipeline that would read it: it would be recorded and silently not propagated. """ tables = problem.transform.modal_tables metric = problem.linear.modal_metric if tables is None: if metric is not None: msg = ( "solprop executes linear.modal_metric as part of the general modal " "route, and this problem carries no transform.modal_tables for it to " "belong to" ) raise TranslationError(msg) return if metric is None or metric.kind not in ("identity", "dense"): kind = "absent" if metric is None else f"of kind {metric.kind!r}" msg = ( "solprop executes a general modal guide in a basis certified " "orthonormal in true power -- an identity linear.modal_metric, or the " "dense metric of a declared unitary change of basis of one -- and this " f"problem's is {kind}; a diagonal metric is a power-orthogonal basis " "with unequal channel norms, which nothing in this package builds and " "no backend has measured" ) raise TranslationError(msg) defect = float(np.max(metric.error)) if defect > DEFAULT_GRAM_ATOL: # An identity metric is executed as the identity and nothing downstream reads # the error row again, so an ungated certificate is an unbounded silent error. msg = ( f"linear.modal_metric.error is {defect:.4g}, above the " f"{DEFAULT_GRAM_ATOL:.4g} solprop will call the identity: this basis " "is that far from orthonormal where it was sampled, and a continuous " "wave's da/dz would be wrong by about that much" ) raise TranslationError(msg) _check_dense_metric(tables, metric) if tables.synthesis is None or tables.projection is None: msg = ( "solprop executes a general modal guide through the synthesis and " "projection maps of transform.modal_tables, and this problem carries " "neither: a reference sampled over a path of positions has no execution " "map" ) raise TranslationError(msg) if tables.synthesis.shape[0] != 1 or tables.synthesis.shape[1] != 1: _check_moving_maps(problem) weight = problem.linear.power_weight_constant if weight is None or not np.all(weight == 1.0): msg = ( "solprop executes a general modal guide whose Poynting amplitude is " "already the true-power amplitude, so linear.power_weight is the " "constant one; this problem's is " f"{problem.linear.power_weight_representation}" ) raise TranslationError(msg) _check_channel_responses(problem) check_regional_responses(problem.responses.regional_responses) def _check_dense_metric( tables: ModalTransformTables, metric: ModalMetricTables ) -> None: """Refuse a dense metric that is not a unitary change of basis, measuring it. The route propagates through the **diagonal** cumulative flow and measures the step controller's norm on the coordinate amplitudes, both of which are the basis's own only where that basis is orthonormal in true power. A declared unitary change of basis of a certified orthonormal reference stays there -- ``W' = I + U.H delta U`` has the same spectral departure as ``delta`` -- and a nonunitary one does not. """ block = metric.dense if block is None: return if metric.gauge_id != tables.gauge_id: msg = ( f"linear.modal_metric describes the basis {metric.gauge_id!r} and " f"transform.modal_tables is in {tables.gauge_id!r}: a metric of another " "basis than the reference it is executed beside would weight the wrong " "channels" ) raise TranslationError(msg) departure = max( metric_departure(block[interval, degree]) for interval in range(block.shape[0]) for degree in range(block.shape[1]) ) if departure > MAX_DENSE_METRIC_DEPARTURE: msg = ( f"linear.modal_metric is dense and {departure:.4g} from the identity, " f"above the {MAX_DENSE_METRIC_DEPARTURE:.4g} solprop will execute. " "The route propagates through the diagonal cumulative flow and " "measures the controller's norm on the coordinate amplitudes, so it " "admits a dense metric only as a unitary change of basis of a " "certified orthonormal reference, whose departure is the reference's " "own; a nonunitary transform leaves a genuinely nonorthogonal basis, " "whose flow is linear.coupled_flow and whose transport is unmeasured" ) raise TranslationError(msg) def _check_moving_maps(problem: "PropagationProblem") -> None: """Refuse a moving guide's maps beside anything but the flow of their connection. Moving maps with no connection are a guide whose modes change shape and exchange no power, which is the adiabatic approximation the route exists to replace. """ flow = problem.linear.coupled_flow if ( flow is None or flow.connection is None or set(flow.section_methods) != {"frozen_residual"} ): described = ( "no coupled flow" if flow is None else f"a flow of {sorted(set(flow.section_methods))} sections" + ("" if flow.connection is not None else " and no connection") ) msg = ( "solprop executes a moving guide's maps beside the flow that carries " f"its connection, 'frozen_residual' on every section, and this problem " f"carries {described}: maps that move with no connection are the " "adiabatic approximation the moving route replaces" ) raise TranslationError(msg) def _check_channel_responses(problem: "PropagationProblem") -> None: """Refuse a channel response a general modal guide would carry and not propagate. A channel response is one the channel routes' node pipeline evaluates. """ responses = problem.responses carried = [ name for name, present in ( ("kerr_coefficients", responses.kerr_coefficients is not None), # The general route's own dispersive channels name their node regions; # a population's leaf has none and would not be read. ( "dispersive_kerr", responses.dispersive_kerr is not None and responses.dispersive_kerr.regions is None, ), ("population_channels", bool(responses.population_channels)), ("raman_terms", bool(responses.raman_terms)), ("envelope_plasma", responses.envelope_plasma is not None), ) if present ] if carried: msg = ( "solprop executes transform.modal_tables with its own " "responses.regional_responses and no channel response, and this problem " f"also carries responses.{', responses.'.join(carried)}: the general " "route's source replaces the channel node pipeline that would read them, " "so they would be recorded and not propagated" ) raise TranslationError(msg)