solprop.coupling.port

The receiving side of a transfer: a simulation’s input port and its launch.

An InputPort describes what a simulation can receive at its entrance, already sampled (SEP 31, section 5.1): the route, the temporal lattice and basis with their identities, the entrance plane and the frame accumulated there, the native metric Q, the reference index of the medium, and the coupling models it admits. solprop.driver.simulation.Simulation.input_port() returns one; the translation layer fills it. It is a P-layer value type, so that a coupling computed with NumPy alone never imports the translation layer.

A CouplingLaunch is bound to one port: it carries the port, the target coefficients and the reference origin the launched run inherits, and solprop.driver.simulation.Simulation.with_input() refuses it for any other port, whatever the array shapes. solprop.coupling.coupler.couple() computes one.

Module Attributes

ENTRANCE_TOLERANCE	Relative agreement of two entrance positions, of the larger of 1 m and abs(z).
METRIC_TOLERANCE	Largest relative difference of two admittance metrics that counts as one medium.

Functions

check_same_medium(source, target)	Refuse a relaunch across a change of medium or metric.
occupied_outside(samples, grid)	Return the share of a record's squared samples outside a grid's active band.

Classes

CouplingLaunch(port, samples, origin, model, ...)	A launch bound to one input port.
InputPort(route, grid, basis, shape, ...[, ...])	What a simulation can receive at its entrance, already sampled.

class solprop.coupling.port.CouplingLaunch(port, samples, origin, model, provenance)

Bases: object

A launch bound to one input port.

Attributes:

portInputPort

The port it was computed for; its grid, basis, metric and entrance are the launch’s identity.

samplesnumpy.ndarray

The target coefficients, optics-convention stored spectrum, shape port.shape, read-only, in the port’s native units.

originPlaneReference

The reference of the launched run’s path origin: the launched spectrum’s reference minus the frame the port has accumulated at its entrance. The launched run’s planes add their own frame to it.

modelstr

The coupling model that produced it.

provenancecollections.abc.Mapping

JSON-ready record of where it came from: the source plane’s provenance and the model, recorded in the launched run’s configuration.

Raises:

CouplingError

If the samples do not have the port’s shape or are not finite.

internal()

Return the samples in the internal convention a simulation takes.

Returns:

numpy.ndarray

solprop.fourier.spectrum_to_internal() of samples.

model: str

origin: PlaneReference

port: InputPort

provenance: Mapping[str, object]

record()

Return the coupling provenance a launched run records.

Returns:

dict

The model, the port identity, the origin and the source provenance.

samples: Complex[ndarray, 'n_modes n_pol n_omega']

solprop.coupling.port.ENTRANCE_TOLERANCE = 1e-12

Relative agreement of two entrance positions, of the larger of 1 m and abs(z).

A launch names its entrance by position; within this, two positions are the same plane, as a plane the run reached by summing steps sits within a few ulp of it.

class solprop.coupling.port.InputPort(route, grid, basis, shape, geometry, frame, metric, reference_index=None, nodes=None, node_weights=None, electric=None, magnetic=None, models=('same_basis',), profiles=None, contrast=None, normalised_frequency=None)

Bases: object

What a simulation can receive at its entrance, already sampled.

Attributes:

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

The receiving representation.

gridsolprop.grid.TimeGrid

The receiving temporal grid.

basisPlaneBasis

The receiving basis, with its identity, labels and transverse grid.

shapetuple of int

The launch’s (n_modes, n_pol, n_omega).

geometryPlaneGeometry

The entrance plane: its position along the receiving path and side.

framePlaneReference

The receiving run’s own frame accumulated from its path origin to the entrance, without any inherited origin: zero at a path’s start.

metricPlaneMetric

The native metric Q at the entrance: the identity for ordinary true-power coefficients, the basis Gram (optics convention) for a general guide, the axial admittance for a spatial grid.

reference_indexnumpy.ndarray or None, optional

Real phase index of the entrance medium at each bin, shape (n_omega,), where the route defines one (a spatial medium).

nodesnumpy.ndarray or None, optional

Transverse nodes (x, y) the target basis is sampled at, m, shape (n_nodes, 2); None where phase 2 samples no profiles.

node_weightsnumpy.ndarray or None, optional

Their area weights, m^2, shape (n_nodes,).

electricnumpy.ndarray or None, optional

The target basis’s electric field at the nodes, optics convention, in V/(m sqrt(W)), shape (n_nodes, 3, n_modes, n_omega): a general guide’s E reference at its entrance.

magneticnumpy.ndarray or None, optional

Its magnetic field in A/(m sqrt(W)), the same shape.

modelstuple of str, optional

The coupling models of CouplingModel the port admits; same_basis always.

profilessolprop.coupling.models.ScalarModeBasis or None, optional

The scalar transverse profiles of an ordinary mode set’s columns: a capillary’s HE1m modes or a weakly guiding step-index fibre’s LP0m modes.

contrastnumpy.ndarray or None, optional

The weak-guidance screen \(\Delta = \max|n^2 - n_{\rm ref}^2|/(2n_{\rm ref}^2)\) over the guide’s dielectric regions at each bin, shape (n_omega,), zero off the active band; None where the screen does not apply (a capillary wall, a spatial medium).

normalised_frequencynumpy.ndarray or None, optional

A step-index general guide’s normalised frequency \(V = (\omega/c)\,a\sqrt{n_{\rm co}^2 - n_{\rm cl}^2}\) at its entrance at each bin, shape (n_omega,), zero off the active band: what the recorded vector envelope’s range is checked against. None for every other port.

Raises:

CouplingError

If the shape disagrees with the grid or the basis kind with the route.

accepts(other)

Return why a launch bound to other cannot enter this port, or None.

Parameters:

otherInputPort

The port a launch was bound to.

Returns:

str or None

The first disagreement – route, lattice, basis, shape, entrance, orientation or metric (the medium) – named; None when the two are the same port.

basis: PlaneBasis

contrast: Float[ndarray, 'n_omega'] | None = None

electric: Complex[ndarray, 'n_nodes 3 n_modes n_omega'] | None = None

frame: PlaneReference

geometry: PlaneGeometry

grid: TimeGrid

property identity: str

Return the port’s identity: route, lattice, basis and entrance.

Returns:

str

A SHA-256 hex digest; two ports with the same identity accept the same launch.

property lattice: str

Return the identity of the receiving temporal lattice.

Returns:

str

lattice_identity() of grid.

magnetic: Complex[ndarray, 'n_nodes 3 n_modes n_omega'] | None = None

metric: PlaneMetric

models: tuple[str, ...] = ('same_basis',)

node_weights: Float[ndarray, 'n_nodes'] | None = None

nodes: Float[ndarray, 'n_nodes 2'] | None = None

normalised_frequency: Float[ndarray, 'n_omega'] | None = None

profiles: ScalarModeBasis | None = None

reference_index: Float[ndarray, 'n_omega'] | None = None

route: Literal['modal', 'general_modal', 'radial', 'cartesian', 'planar']

shape: tuple[int, int, int]

solprop.coupling.port.METRIC_TOLERANCE = 1e-10

Largest relative difference of two admittance metrics that counts as one medium.

The same medium at the same plane evaluates its admittance through one arithmetic path (SEP 34) and agrees to rounding; a different medium differs by its index, a few parts in a million for a gas. Anything between is a different medium.

solprop.coupling.port.check_same_medium(source, target)

Refuse a relaunch across a change of medium or metric.

Used by InputPort.accepts() and by the same_basis model.

Parameters:

sourcePlaneMetric

The plane’s metric.

targetPlaneMetric

The port’s metric.

Raises:

CouplingError

If the kinds differ, or the admittances or Grams differ by more than METRIC_TOLERANCE.

solprop.coupling.port.occupied_outside(samples, grid)

Return the share of a record’s squared samples outside a grid’s active band.

Parameters:

samplesnumpy.ndarray

Stored spectrum, shape (n_modes, n_pol, n_omega).

gridsolprop.grid.TimeGrid

The receiving grid, on the same lattice.

Returns:

float

The share, zero for a zero record.