solprop.coupling.transport

solprop.coupling.transport(plane, elements, *, geometry=None, frame=None)

Apply an ordered sequence of linear elements to a field plane.

Parameters:

planesolprop.coupling.FieldPlane

A radial or Cartesian plane with its medium. A modal plane is refused: its guide field is synthesised first by Outcouple.

elementssequence

Elements of solprop.coupling.elements, applied in order. A solprop.optics.Chain or another known transfer function is one frequency-only block at its position; an unknown callable needs an explicit solprop.coupling.elements.SpectralTransfer with its calibration.

geometrysolprop.coupling.PlaneGeometry or None, optional

The output plane, declared in the receiving system’s coordinates; its axes must be the transported ones. None moves the input plane along its path.

framesolprop.linear.Frame or None, optional

The frame the plane is written in, such as the source simulation’s frame: every FreeSpace without its own frame_delay then removes the affine term the run would have removed over its distance. None removes only the delay beta1(omega0) L of the gap’s medium, as the report records.

Returns:

tuple

The plane at the last element’s output – reference, geometry, medium, metric and provenance updated – and the TransportReport.

Raises:

CouplingError

If the plane cannot be transported, its exterior is unknown and a gap propagates it, an item is neither an element nor a transfer function, an element refuses, or a declared geometry disagrees with the transported axes.

Examples

>>> from solprop.coupling import (FieldPlane, FreeSpace, PlaneGeometry,
...                               ThinLens, transport)
>>> from solprop.grid import EnvelopeGrid, RadialGrid
>>> from solprop.pulses import GaussianPulse, SpatialPulse
>>> from solprop.spatial import SpatialMedium
>>> grid = EnvelopeGrid.from_limits(0.1, 800e-9, (750e-9, 850e-9), 200e-15)
>>> air = SpatialMedium()
>>> beam = SpatialPulse(GaussianPulse(wavelength=800e-9, fwhm=30e-15,
...                                   energy=1e-6), 1e-3)
>>> plane = FieldPlane.from_pulse(beam, grid, PlaneGeometry(0.0),
...                               space=RadialGrid(4e-3, 128), medium=air)
>>> focus, report = transport(plane, [ThinLens(1.0, model_error=1e-3),
...                                   FreeSpace(0.5, air)])
>>> f"{report.energy_out:.4e} J at z = {focus.geometry.z} m"
'1.0000e-06 J at z = 0.5 m'