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 (same_basis, scalar_paraxial, vector_paraxial) and returns a CouplingResult: the launch and an immutable CouplingReport. An approximate coupling is admitted against its model_error budget through a list of AdmissionItem s, each a relative energy discrepancy with its ItemScope, whose counted items must sum to at most the budget; an apparent gain below PASSIVITY_ROUNDING is rounding. target_columns() gives a scalar target profile’s columns in a spatial plane’s own spectral quadrature, where the overlaps are taken by Parseval.

Three quadratic forms are kept apart throughout: 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; and Q, a representation’s native power metric. Only the scalar model, in M_0, reports an uncaptured energy. The measures, the models, every admission item and the recorded envelopes are in docs/guide/workflows/coupling.md, section “Coupling between different representations”.

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]#

Whether the item is within its own cap.

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]#

Sum of the counted admission items.

At most model_error for an admitted coupling.

captured: Float[ndarray, 'n_omega'] | None#
property captured_energy: float | None[source]#

Captured energy in the common metric, J, or None where undefined.

captured_reason: str#
certificate: AdiabaticAdmission | None#
property efficiency: float | None[source]#

Launched energy as a share of the incident energy.

None when nothing is incident, where it is undefined.

exterior: str#
incident: Float[ndarray, 'n_omega']#
property incident_energy: float[source]#

Whole incident energy, J.

items: tuple[AdmissionItem, ...]#
launched: Float[ndarray, 'n_omega']#
property launched_energy: float[source]#

Energy the launch carries into the target, J.

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]#

Incident energy each bin leaves outside the target, not clipped.

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]#

Uncaptured energy in the common metric, J, not clipped.

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).