solprop.coupling.envelopes#
Recorded benchmark envelopes of the approximate coupling models’ provider pairs.
SEP 31 section 4.3 admits a provider pair to an approximate coupling model only with
an independent benchmark envelope for what the model omits, recorded with its
identity, range and independently bounded numerical error, and never extrapolated.
Each PairEnvelope or FieldEnvelope is one such record:
CAPILLARY_ENVELOPE: the scalar J0 profile against Marcatili’s leaky HE1m core field. Its discrepancy depends on the field (mode m departs by about \(u_m\delta\)), so no fixed bound covers every field usefully: it is aFieldEnvelope, evaluated for the field coupled in closed form (solprop.coupling._leaky), with its range and numerical error recorded.STEP_INDEX_ENVELOPE: the weak-guidance LP01 overlap of two step-index fibres against the full-vector flux overlap of their exact HE11 fields (solprop.modes.stepindex.StepIndexMode.electromagnetic_field()); it replaces the contrast screen within its range.STEP_INDEX_BEAM_ENVELOPE: a beam’s scalar LP01 overlap against its full-vector coupling into the exact HE11 pair, maximised over every field inside the widest admitted cone; it scales linearly with the fibre’s contrast.VECTOR_STEP_INDEX_ENVELOPE: the vector model into aStepIndexProviderguide against a full-vector mode-matching solution of the entrance facet; it scales with the square of the contrast.
The numbers were measured by the oracles in tests/coupling/test_envelopes.py, which
recompute them and hold the recorded bounds; docs/guide/workflows/coupling.md,
section “The admission budget and the report”, describes each envelope.
Module Attributes
The capillary HE1m envelope, evaluated per field; |
|
The weak-guidance step-index LP01 envelope; |
|
The beam-into-fibre LP01 envelope; |
|
The vector model's step-index facet envelope; |
Classes
|
An approximate model's omitted physics, evaluated for each field coupled. |
|
A recorded benchmark envelope of one provider pair under an approximate model. |
- solprop.coupling.envelopes.CAPILLARY_ENVELOPE = FieldEnvelope(identity='capillary-he1m-scalar-vs-leaky-marcatili-field-2026-11', family='capillary', ranges=mappingproxy({'modes': (1.0, 24.0), 'radius_ratio': (0.5, 2.0), 'leaky': (0.0, 0.01)}), numerical=1e-08, reference="Marcatili's leaky HE1m core field J0(u_m (1 - i delta) r/a), delta = |nu_n| c/(omega a), against the scalar J0 profile, evaluated for the field coupled at every bin: the summed change of the power launched into each channel, |G^-1 o|^2 on unit profiles, relative to the incident power (a beam's energy on its plane, a capillary exit's modal power). Closed-form Lommel overlaps; a beam's leaky overlaps from the Taylor series of the leaky profile in delta, its remainder bounded; a capillary exit's exactly. Numerical error below 1e-8: Lommel's midpoint branch, 2e-9 relative. Checked against an independent polar Gauss-Legendre quadrature for centred, displaced, tilted and structured beams on Cartesian and radial planes into 4 to 24 HE1m, and capillary exits of random complex amplitudes at radius ratios 0.5 to 2 into up to 24 HE1m")#
The capillary HE1m envelope, evaluated per field;
radius_ratiois source over target radius (1 for an incident beam),modesthe highest HE1m radial order of the pair,leakythe largerleaky()of the pair over the occupied bins (about 5.0e-3 for a 37.5 um silica capillary at 800 nm),fieldthe field’s evaluated discrepancy weighted by incident energy.
- class solprop.coupling.envelopes.FieldEnvelope(identity, family, ranges, numerical, reference)[source]#
Bases:
objectAn approximate model’s omitted physics, evaluated for each field coupled.
Where the discrepancy depends so strongly on the field that no recorded bound covers every field usefully, the coupling evaluates it for the field at hand and reports it as the
fieldrange parameter; the record holds the range the evaluation is qualified over, its numerical error and what it is checked against. The same interface asPairEnvelope(ADR-081).- Attributes:
- identitystr
The envelope’s name, recorded in a coupling report.
- family{‘capillary’}
The profile family of the pair’s guided members.
- rangescollections.abc.Mapping
Each range parameter’s closed interval
(low, high); a pair outside any one is not covered.- numericalfloat
The evaluation’s numerical error, dimensionless, added to the allowance.
- referencestr
What the evaluation computes and what it is checked against.
- allowance(parameters)[source]#
Return the envelope’s energy allowance for a covered field.
- Parameters:
- parameterscollections.abc.Mapping
The pair’s range parameters and
field, the evaluated discrepancy.
- Returns:
- float
Dimensionless:
fieldplus numerical.
Examples
>>> from solprop.coupling import CAPILLARY_ENVELOPE as envelope >>> envelope.allowance({"field": 2e-3}) == 2e-3 + envelope.numerical True
- covers(parameters)[source]#
Return why a pair lies outside the envelope, or None if it is covered.
- Parameters:
- parameterscollections.abc.Mapping
The pair’s value of each range parameter.
- Returns:
- str or None
The first parameter outside its range, named with its value; None when every parameter is inside.
- class solprop.coupling.envelopes.PairEnvelope(identity, family, ranges, bound, numerical, reference, scaled_by=None)[source]#
Bases:
objectA recorded benchmark envelope of one provider pair under an approximate model.
- Attributes:
- identitystr
The envelope’s name, recorded in a coupling report.
- family{‘capillary’, ‘step_index’, ‘step_index_vector’}
The profile family of the pair’s guided members: the target, and a modal source (an incident beam has none); for the vector model, the target guide’s provider.
- rangescollections.abc.Mapping
Each range parameter’s closed interval
(low, high); a pair outside any one is not covered.- boundfloat
The largest measured difference of captured energy share, model against the independent reference, over the range, dimensionless, numerical error included: an energy discrepancy relative to the incident energy.
- numericalfloat
The independently estimated numerical error of the measurement, included in bound.
- referencestr
What the independent reference is.
- scaled_bystr or None, optional
A range parameter the discrepancy grows with: the allowance is then bound times that parameter over its range’s upper end (
allowance()). None (the default) holds bound over the whole range.
- allowance(parameters)[source]#
Return the envelope’s energy allowance for a covered pair.
- Parameters:
- parameterscollections.abc.Mapping
The pair’s value of each range parameter.
- Returns:
- float
Dimensionless: bound, scaled linearly by scaled_by when it is set.
Examples
>>> from solprop.coupling import STEP_INDEX_BEAM_ENVELOPE as envelope >>> high = envelope.ranges["contrast"][1] >>> envelope.allowance({"contrast": 0.5 * high}) == 0.5 * envelope.bound True
- covers(parameters)[source]#
Return why a pair lies outside the envelope, or None if it is covered.
- Parameters:
- parameterscollections.abc.Mapping
The pair’s value of each range parameter.
- Returns:
- str or None
The first parameter outside its range, named with its value; None when every parameter is inside.
- solprop.coupling.envelopes.STEP_INDEX_BEAM_ENVELOPE = PairEnvelope(identity='step-index-beam-lp01-vs-vector-he11-2026-10', family='step_index', ranges=mappingproxy({'contrast': (0.0, 0.01), 'v_target': (1.5, 2.4), 'modes': (1.0, 1.0)}), bound=0.01, numerical=1e-12, reference="the full-vector flux coupling 1/4 int(E x h* + e* x H).z dA of an incident field into the exact unit-power HE11 even and odd modes (StepIndexMode.electromagnetic_field), the field's H and E_z from its own plane-wave spectrum in the core index, against the scalar LP01 overlap the model takes, both in the common measure M0; evaluated in the transverse Fourier plane by azimuthal decomposition and Gauss-Legendre Hankel transforms, inside the widest admitted cone (1 - cos theta = 1/8). The discrepancy of captured energy over incident energy, maximised over every field in that cone (the largest eigenvalue modulus of the difference of the two rank-two capture forms), is 0.467 Delta at V 1.5, falling to 0.284 Delta at V 2.4 (conservative there: the cone's edge truncates the widening HE11 spectrum); at V 1.5 it is linear in Delta from 5e-4 to 1e-2 and independent of the core index and the wavelength: largest 4.67e-3 at Delta 0.01 and V 1.5. Gaussian beams (waists 0.5a to 2.6a, displaced to 0.5a and tilted to half the acceptance angle along x and y, x-polarised) reach 3.3e-3. The bound is twice the largest per unit contrast, rounded up, so the allowance is scaled by Delta/1e-2; refining the quadrature changes the maximum by 2e-13", scaled_by='contrast')#
The beam-into-fibre LP01 envelope;
contrastis the fibre’s largest|n^2 - n_ref^2|/(2 n_ref^2)against its core over the occupied bins,v_targetits normalised frequency at the profile wavelength,modesthe highest LP0m radial order (LP01 only: V below 2.405 guides no other). The bound holds for any incident field inside the admitted cone; the angular item counts what lies outside it, and the source-metric item the beam’s medium.
- solprop.coupling.envelopes.STEP_INDEX_ENVELOPE = PairEnvelope(identity='step-index-lp01-vs-vector-he11-2026-10', family='step_index', ranges=mappingproxy({'contrast': (0.0, 0.01), 'v_source': (1.5, 2.4), 'v_target': (1.5, 2.4), 'radius_ratio': (0.7, 1.43), 'modes': (1.0, 1.0)}), bound=0.0003, numerical=1e-12, reference='full-vector flux overlap of StepIndexMode.electromagnetic_field (exact bound HE11 even, E and H) of the two fibres on an independent polar quadrature; core 1.45, contrast 0.001 to 0.01, V 1.5 to 2.4 and radius ratios 0.7 to 1.43 at 1064 nm (constant indices: the overlaps depend on V alone); largest difference 2.92e-4, at contrast 0.01, V 2.4 and ratio 0.7', scaled_by=None)#
The weak-guidance step-index LP01 envelope;
contrastis the largest|n^2 - n_ref^2|/(2 n_ref^2)of either fibre,v_*each fibre’s normalised frequency at its profile wavelength,radius_ratiosource over target core radius,modesthe highest LP0m radial order of the pair (LP01 only).
- solprop.coupling.envelopes.VECTOR_STEP_INDEX_ENVELOPE = PairEnvelope(identity='step-index-vector-facet-mode-matching-2026-10', family='step_index_vector', ranges=mappingproxy({'contrast': (0.0, 0.05), 'v': (1.5, 8.0), 'contrast_squared': (0.0, 0.0025)}), bound=0.003, numerical=2e-05, reference="independent full-vector mode matching of the planar entrance facet (incident and reflected fields in the core-index input medium, the fibre's forward guided and radiation fields, tangential E and H continuous), solved per azimuthal order in a conducting cylinder of 30 core radii on its own 300 TE and 300 TM Bessel fields, against the model's flux pairing with the same incident H. The omitted share summed over an order's guided modes is a Hermitian form of the incident field: its largest eigenvalue modulus inside the widest admitted cone (1 - cos theta = 1/8) bounds every field of any shape and polarisation, and orders do not mix. Swept at contrast 0.05 (the range's top) over V 1.5 to 8 with points 0.01 to 0.3 above every exact cutoff, each order's guided count held to the cutoffs: largest 1.371e-3 at V 3.905 (order one, HE12 just above its cutoff), 1.24e-3 just above the TE01/TM01 cutoff, 7.4e-4 at V 1.5. A guided mode wholly in the cladding approaches the normal-incidence Fresnel ceiling R(2 - R)/(1 - R) = 1.39e-3 (about Delta**2/2), which no resolved case exceeds; within 0.04 to 0.07 above the HE12 and HE13 cutoffs no cylinder up to 60a holds the newborn mode, so that band is bounded by the ceiling, not resolved. Bound twice the ceiling, numerical included; widening the cylinder to 45a and 60a changes the resolved values by at most 1.2e-5. It is second order in the index step (halving the contrast quarters it; 0.50 to 0.55 Delta**2 at the worst point for contrasts 0.0025 to 0.05), so the allowance is scaled by the squared contrast over 0.05**2", scaled_by='contrast_squared')#
The vector model’s step-index facet envelope;
contrastis the guide’s|n^2 - n_ref^2|/(2 n_ref^2),vits normalised frequency at the entrance andcontrast_squaredthe square of the contrast, each weighted by the incident energy over the occupied bins. It bounds the energy launched into all guided modes together, not each channel’s share, for any incident field inside the admitted cone. It covers the reflection and backward fields at the facet, not the incident beam’s H closure (the angular item) or the guide’s tabulation, and a beam in the core’s index only, since a bulk index change is a separate planar interface (SEP 31, section 4.3).