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
Apparent gain of a whitened map below which it is rounding, not a model defect. |
|
What an admission item bounds: this field, every input of the map, or the model. |
Functions
|
Couple a field plane into an input port under a declared model. |
|
Return scalar profiles in a spatial grid's own column representation. |
Classes
|
One term of a coupling's admission budget (SEP 31, section 4.3). |
|
The structured account of one coupling (SEP 31, sections 4.7 and 5.3). |
|
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:
objectOne term of a coupling’s admission budget (SEP 31, section 4.3).
- Attributes:
- namestr
angular,contrast,target metric,source metric,closure,passivity,envelopeornumerical.- 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.
- class solprop.coupling.coupler.CouplingReport(model, model_error, reference_index, incident, launched, captured, captured_reason, items, exterior, certificate, source, port)[source]#
Bases:
DisplayedThe 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 forsame_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.
- property captured_energy: float | None[source]#
Captured energy in the common metric, J, or
Nonewhere undefined.
- certificate: AdiabaticAdmission | None#
- property efficiency: float | None[source]#
Launched energy as a share of the incident energy.
Nonewhen nothing is incident, where it is undefined.
- incident: Float[ndarray, 'n_omega']#
- items: tuple[AdmissionItem, ...]#
- launched: Float[ndarray, 'n_omega']#
- reference_index: Float[ndarray, 'n_omega']#
- class solprop.coupling.coupler.CouplingResult(launch, report)[source]#
Bases:
objectA 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_basisExact 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_paraxialA 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_paraxialA 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).