solprop.coupling.coupler#

Couple a field plane into a simulation’s input port (SEP 31, sections 4.3 and 4.7).

couple() is the one public path from a FieldPlane to a target-bound CouplingLaunch. It applies one of the three models of CouplingModel and returns a CouplingResult: the launch and an immutable CouplingReport.

Measures. Three quadratic forms are kept apart (section 4.3): F, the Hermitian E/H flux pairing of a modal basis; G = S^H M S, the scalar least-squares Gram in the common paraxial measure \(M_0 = Y_0\,dA/2\), \(Y_0 = n_{\rm ref}\varepsilon_0c\); and Q, a representation’s native power metric. Only in the common positive metric M_0 does the orthogonal-residual identity \(\|f\|^2_M = a^\dagger Ga + \|f - Sa\|^2_M\) hold, so only the scalar model reports an uncaptured energy; the others report the incident and launched energies and leave the difference unattributed.

Overlaps in the plane’s own quadrature. A spatial plane’s columns are the Hankel or Fourier spectrum of its field, so the scalar overlap of a target profile is taken by Parseval in that spectral quadrature, with the profile’s closed-form transform (hankel()): the incident norm, the overlaps and the Gram all use one quadrature, and the identity above holds to rounding. A modal source is overlapped on a composite Gauss–Legendre rule that breaks at both core radii.

Admission (section 4.3). Each approximate coupling is admitted against its model_error budget \(\epsilon_m\) through a list of AdmissionItem s, each a relative energy discrepancy:

angular: \([d(E_{\rm in}) + d_{\rm target}]/U\) with \(1 - \cos\theta_* = \epsilon_m/8\) and \(d = (1 - \cos\theta_*)U_{\rm cone} + U_{\rm tail}\) (section 4.6), for the incident field and for the retained target subspace. The cone term is the cone rule’s allocation, about \(\epsilon_m/8\) of the cone share, not a measured defect; only the tail beyond \(\theta_*\) is measured;
contrast: the weak-guidance screen \(\Delta \le \epsilon_m/8\) of a solid provider, or the recorded pair envelope that replaces it; not applied to a capillary wall;
target metric and source metric: the relative defect between G (or F) and the target’s native Q, and between M_0 and the source’s native metric, each at most \(\epsilon_m/8\);
closure (vector model): \(2\delta + \delta^2\) of the H-closure field error \(\delta\), at most \(\epsilon_m/8\);
passivity: the whitened certificate \(C^\dagger Q_BC \preceq Q_A\); an apparent gain within the model’s own defects is reported as a model defect, never rescaled or clipped, and a larger one refuses;
envelope: the recorded pair envelope’s allowance (scaled by the pair’s leaky parameter for a capillary, by the fibre’s contrast for a beam into a step-index fibre, by the squared contrast for the vector model into a step-index guide), plus the incident share of any bins outside its range; a general guide without a recorded envelope (a graded index) reports it without a value, uncounted;
numerical: quadrature, representation and domain errors, an amplitude error \(\delta\) entered as \(2\delta + \delta^2\).

The counted items must sum to at most \(\epsilon_m\). A source plane’s SEP 34 path certificate is carried separately in the report. A zero field is a valid zero launch with an undefined efficiency.

Module Attributes

`PASSIVITY_ROUNDING`	Apparent gain of a whitened map below which it is rounding, not a model defect.
`ItemScope`	What an admission item bounds: this field, every input of the map, or the model.

Functions

`couple`(plane, port, *, model)	Couple a field plane into an input port under a declared model.
`target_columns`(profiles, space)	Return scalar profiles in a spatial grid's own column representation.

Classes

`AdmissionItem`(name, value, allowance, ...[, ...])	One term of a coupling's admission budget (SEP 31, section 4.3).
`CouplingReport`(model, model_error, ...)	The structured account of one coupling (SEP 31, sections 4.7 and 5.3).
`CouplingResult`(launch, report)	A launch bound to its port, and the account of how it was computed.

class solprop.coupling.coupler.AdmissionItem(name, value, allowance, counted, scope, note='')[source]#

Bases: object

One term of a coupling’s admission budget (SEP 31, section 4.3).

Attributes:

namestr: angular, contrast, target metric, source metric, closure, passivity, envelope or numerical.
valuefloat or None: The relative energy discrepancy it bounds, dimensionless; None where the item does not apply (note says why).
allowancefloat or None: Its own cap, where the model gives it one (\(\epsilon_m/8\)); None when only the total budget limits it.
countedbool: Whether value is part of the budget’s sum. A screen (contrast) bounds a model’s validity, not an energy, and is not counted.
scope{‘field’, ‘map’, ‘model’}: Whether it bounds this field only, every input of the map, or the model.
notestr, optional: What it measured, or why it does not apply.

allowance: float | None#

counted: bool#

name: str#

note: str = ''#

property passed: bool[source]#

Return whether the item is within its own cap.

Returns:

bool: True when it has no value or no cap, or its value is at most the cap.

scope: Literal['field', 'map', 'model']#

value: float | None#

class solprop.coupling.coupler.CouplingReport(model, model_error, reference_index, incident, launched, captured, captured_reason, items, exterior, certificate, source, port)[source]#

Bases: Displayed

The structured account of one coupling (SEP 31, sections 4.7 and 5.3).

Energies are per bin, J, in the measure each names; the totals are their sums.

Attributes:

modelstr: The coupling model.
model_errorfloat or None: Its budget; None for same_basis.
reference_indexnumpy.ndarray: \(n_{\rm ref}\) of the common measure at each bin, shape (n_omega,); zero where it is not defined.
incidentnumpy.ndarray: The incident field’s energy over its whole plane, shape (n_omega,): in the common measure \(M_0\) for the approximate models, the plane’s own metric for same_basis.
launchednumpy.ndarray: The launch’s energy in the target’s native metric, shape (n_omega,): what the receiving run’s entrance plane carries.
capturednumpy.ndarray or None: The captured energy \(a^\dagger Ga\) in the common metric, shape (n_omega,); None where the model has no common positive metric.
captured_reasonstr: Why captured is None; empty otherwise.
itemstuple of AdmissionItem: The admission budget’s terms.
exteriorstr: What the source plane says beyond its record: 'zero' or 'unknown' (unobserved tails are unknown, not lost).
certificatesolprop.adiabatic.AdiabaticAdmission or None: The source plane’s SEP 34 path certificate, carried separately: its scope is the linear background’s forward field, so it bounds the source’s background path, not the coupling.
sourcecollections.abc.Mapping: The source plane’s provenance.
portstr: The target port’s identity.

property budget: float[source]#

Return the sum of the counted admission items.

Returns:

float: Dimensionless; at most model_error for an admitted coupling.

captured: Float[ndarray, 'n_omega'] | None#

property captured_energy: float | None[source]#

Return the captured energy in the common metric.

Returns:

float or None: J; None where it is not defined.

captured_reason: str#

certificate: AdiabaticAdmission | None#

property efficiency: float | None[source]#

Return the launched energy as a share of the incident energy.

Returns:

float or None: Dimensionless; None when nothing is incident, where it is undefined.

exterior: str#

incident: Float[ndarray, 'n_omega']#

property incident_energy: float[source]#

Return the whole incident energy.

Returns:

float

items: tuple[AdmissionItem, ...]#

launched: Float[ndarray, 'n_omega']#

property launched_energy: float[source]#

Return the energy the launch carries into the target.

Returns:

float

model: str#

model_error: float | None#

port: str#

reference_index: Float[ndarray, 'n_omega']#

source: Mapping[str, object]#

property uncaptured: Float[ndarray, 'n_omega'] | None[source]#

Return the incident energy each bin leaves outside the target, not clipped.

Returns:

numpy.ndarray or None: incident - captured, J, in the common positive metric where the orthogonal-residual identity makes it a nonnegative physical share; None where captured is None.

property uncaptured_energy: float | None[source]#

Return the uncaptured energy in the common metric, not clipped.

Returns:

float or None: J; None where it is not defined.

class solprop.coupling.coupler.CouplingResult(launch, report)[source]#

Bases: object

A launch bound to its port, and the account of how it was computed.

Attributes:

launchsolprop.coupling.port.CouplingLaunch: What solprop.driver.simulation.Simulation.with_input() takes.
reportCouplingReport: The energies, the admission budget and the provenance.

launch: CouplingLaunch#

report: CouplingReport#

solprop.coupling.coupler.ItemScope#

What an admission item bounds: this field, every input of the map, or the model.

alias of Literal[‘field’, ‘map’, ‘model’]

solprop.coupling.coupler.PASSIVITY_ROUNDING = 1e-10#

Apparent gain of a whitened map below which it is rounding, not a model defect.

The certificate’s largest squared singular value is formed from sums over at most a few thousand columns of terms within a few ulp of each other, then whitened by a Cholesky factor of a Gram whose condition is checked; 1e-10 is well above that rounding and well below any model defect worth naming.

solprop.coupling.coupler.couple(plane, port, *, model)[source]#

Couple a field plane into an input port under a declared model.

SEP 31 section 4.3. The plane must already be on the port’s temporal lattice (regrid() moves it), at an identically oriented plane, and inside the port’s active band. Every pair the model is not qualified for is refused by name; nothing restores energy the target does not take, and nothing is rescaled.

same_basis: Exact recovery: a copy for an identical basis; a declared BasisChange; or, for a general modal plane carrying E/H at the port’s own nodes, \(a = F^{-1}B\).
scalar_paraxial: A radial or Cartesian plane into a capillary port or a weakly guiding step-index fibre’s, a capillary plane into another capillary (any radii and mode sets), or a weakly guiding step-index fibre’s plane into another’s, within the recorded envelopes.
vector_paraxial: A radial or Cartesian plane, or an ordinary modal plane with its profiles, into a general modal guide that carries E/H at fixed nodes, with the forward closure \(H_t = Y_0\hat z\times E_t\).

Parameters:

planesolprop.coupling.plane.FieldPlane: The source plane.
portsolprop.coupling.port.InputPort: The receiving port.
modelsolprop.coupling.models.CouplingModel: The model and its budget.

Returns:

CouplingResult: The launch, bound to port, and its report.

Raises:

CouplingError: If the port does not admit the model, the lattice, orientation or band differ, the pair is not one the model is qualified for, or an admission item or the total budget is exceeded.

solprop.coupling.coupler.target_columns(profiles, space)[source]#

Return scalar profiles in a spatial grid’s own column representation.

The columns a profile centred on the grid’s axis would have if it were that grid’s field: on a radial grid its Hankel transform at the grid’s \(k_r\); on a Cartesian grid its Fourier transform \(2\pi\tilde v(|\mathbf k|)\) at the grid’s \(\mathbf k\), with the raw DFT’s origin phase \(e^{i\mathbf k\cdot\mathbf x_0}/(\Delta x\Delta y)\). Both are the continuous transform, in closed form, so a profile’s kink at the core radius is not sampled. Then \(\int v^*f\,dA = \sum_j w_j\,c_j^*s_j\) with the grid’s spectral weights.

Parameters:

profilessolprop.coupling.models.ScalarModeBasis: The profiles.
spacesolprop.grid.RadialGrid or solprop.grid.FreeGrid: The grid.

Returns:

numpy.ndarray: Shape (n_modes, n_columns): in V m per (V/m) on a radial grid, V/m per (V/m) on a Cartesian one, in the internal convention of the grid’s forward transform (the optics-convention columns of a field are conjugated in the transverse phase as well).