solprop.translate.coupling

Sample a translated problem’s entrance into a coupling port (SEP 31).

Two products of the translation layer feed plane exchange. frame_record() is the persisted frame integral of a run: the antiderivatives of the frame quantities its linear operator removed, so that any saved plane’s reference can be rebuilt without the run (output schema 24). input_port() fills the solprop.coupling.port.InputPort of a translated problem’s entrance: its native metric at that plane, the frame it has accumulated there, the entrance medium’s index, the coupling models it admits and what they need: an ordinary mode set’s scalar profiles, and for a general guide that does not move its E/H reference at the nodes and the weak-guidance contrast of its regions (SEP 31, section 4.3). Both read the contract’s own leaves, so a port and a saved plane of the same run see the same numbers.

Functions

frame_record(linear, frequency_origin)	Return the persisted frame integral of a run's linear operator.
guide_contrast(guide, grid)	Return a general guide's core index and weak-guidance contrast at each bin.
input_port(problem, grid, *, route, basis, frame)	Fill the input port of a translated problem's entrance.
port_metric(problem, grid, z)	Return the native metric of a translated problem's state at a plane.
step_index_frequency(guide, grid, z)	Return a step-index guide's normalised frequency at its entrance, per bin.

solprop.translate.coupling.frame_record(linear, frequency_origin)

Return the persisted frame integral of a run’s linear operator.

The operator removed \(R = \beta_0(z) + \beta_1(z)(\omega - \omega_o)\) (docs/dev/conventions.md section 2; solprop.linear.Frame), with \(\beta_0\) zero where the frame keeps it. The record holds the exact Chebyshev antiderivatives \(\Phi_0 = \int_0^z\beta_0\) and \(T = \int_0^z\beta_1\) of the contract’s own frame tables and the frequency origin, which is all solprop.coupling.plane.reference_at() needs.

Parameters:

linearsolprop.translate.linop.LinearOperator

The contract’s linear operator.

frequency_originfloat

\(\omega_o\) in rad/s: the frame’s reference frequency on an envelope grid, zero on a field grid.

Returns:

dict or None

JSON-ready frequency_origin and the phase (rad) and delay (s) antiderivatives, each its breakpoints (m) and per-interval coefficients, lowest degree first; None for an operator supplied without its frame tables.

solprop.translate.coupling.guide_contrast(guide, grid)

Return a general guide’s core index and weak-guidance contrast at each bin.

The core is the region on the axis, whose real phase index is the reference \(n_{\rm ref}\); the contrast is \(\Delta = \max|n^2 - n_{\rm ref}^2|/(2n_{\rm ref}^2)\) over every region’s law and, for a radial-law provider, over its core profile sampled at 33 radii (SEP 31, section 4.3).

Parameters:

guidesolprop.modes.guide.ModalGuide

The guide.

gridsolprop.grid.TimeGrid

The run’s grid.

Returns:

tuple of numpy.ndarray

The reference index and the contrast, each shape (n_omega,), zero off the active positive band.

solprop.translate.coupling.input_port(problem, grid, *, route, basis, frame, medium=None, tables=None, side=None, z=None, modes=(), guide=None)

Fill the input port of a translated problem’s entrance.

The models it admits: same_basis always; scalar_paraxial for an ordinary mode set whose scalar profiles exist (a capillary’s HE1m modes, a step-index fibre’s HE1m modes in the weak-guidance limit), with the core’s index as the reference; vector_paraxial for a general guide whose E/H the port carries, with its core’s index and its regions’ contrast.

Parameters:

problemsolprop.translate.problem.KernelProblem

The translated problem; its launch position is the entrance.

gridsolprop.grid.TimeGrid

Its temporal grid.

route{‘modal’, ‘general_modal’, ‘radial’, ‘cartesian’, ‘planar’}

The receiving representation.

basissolprop.coupling.PlaneBasis

The receiving basis and its identity, as the driver computes it from the run’s record.

framedict or None

frame_record() of the problem; None leaves the entrance frame uncalibrated.

mediumsolprop.spatial.SpatialMedium or None, optional

The bulk medium of a spatial route, for the reference index.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The E/H reference of a general guide; sampled into the port when the guide does not move.

side{‘before’, ‘after’} or None, optional

Side of a declared jump at the entrance.

zfloat or None, optional

An interior entrance, m, inside the problem’s span; None is its launch position.

modessequence of solprop.modes.protocol.Mode, optional

An ordinary modal run’s modes, for their scalar profiles.

guidesolprop.modes.guide.ModalGuide or None, optional

A general modal run’s guide, for its core index and contrast.

Returns:

solprop.coupling.InputPort

The port and the models it admits.

solprop.translate.coupling.port_metric(problem, grid, z)

Return the native metric of a translated problem’s state at a plane.

Parameters:

problemsolprop.translate.problem.KernelProblem

The translated problem.

gridsolprop.grid.TimeGrid

Its temporal grid.

zfloat

The plane’s position, m.

Returns:

solprop.coupling.PlaneMetric

The axial admittance of a spatial run’s plane measure at z (SEP 34), the optics-convention Gram conj(W) of a modal basis that declares one, and the identity for true-power coefficients otherwise.

solprop.translate.coupling.step_index_frequency(guide, grid, z)

Return a step-index guide’s normalised frequency at its entrance, per bin.

\(V = (\omega/c)\,a(z)\sqrt{n_{\rm co}^2 - n_{\rm cl}^2}\), with the core radius at the entrance and the real parts of the core’s and the cladding’s declared laws, is what the recorded vector envelope’s range (solprop.coupling.envelopes.VECTOR_STEP_INDEX_ENVELOPE) is stated in.

Parameters:

guidesolprop.modes.guide.ModalGuide

The guide.

gridsolprop.grid.TimeGrid

The run’s grid.

zfloat

The entrance, m.

Returns:

numpy.ndarray or None

V at each bin, shape (n_omega,), zero off the active positive band; None for a guide whose provider is not a StepIndexProvider.