Shorter start-up: optmat 0.9.1, lazy imports, no numba on the native backend

CHANGELOG.md

@@ -40,6 +40,88 @@ The first public release. It contains:
   `SimulationSettings.adiabatic_accuracy`). `poynting_spectrum` is removed:
   `beam_spectrum` is the axial-flux spectrum. Kernel schema 35 (`flux`) and output
   schema 23 (`flux_model`, `flux_plan`).
+- **Incident beams into general modal guides**
+  ([SEP 31](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0031-simulation-coupling.html),
+  phases 1 and 3). `from_waveguide(provider=..., incident=SpatialPulse(...),
+  coupling=CouplingModel("vector_paraxial", model_error=...))` and `prop_waveguide`
+  launch the share of an incident beam that the guide's channels capture. The beam's
+  energy is met over its whole plane in the core medium, and the light that misses is
+  lost rather than restored. The coupling's `CouplingReport` is recorded in
+  `configuration["launch"]`, and `SpatialPulse.incident` samples a beam normalised over
+  its own plane. The node-sampled `transverse=` profile, its rescaling to `energy=`, the
+  3 % uncaptured warning, `LAUNCH_UNCAPTURED_WARNING` and `IncidentLaunch` are removed;
+  a strongly guiding core is refused by the vector model's contrast screen.
+- **Plane exchange between simulations**
+  ([SEP 31](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0031-simulation-coupling.html),
+  phase 2). `solprop.coupling` holds `FieldPlane`, a coherent field at one plane with
+  its reference, geometry, metric, basis identity and provenance; `regrid`, the direct
+  finite-time Fourier remap between temporal grids with its loss report and no
+  renormalisation; and `InputPort`. `processing.field_plane` reads a saved plane back
+  (refusing a modified-noise run's, whose auxiliary noise phase it does not reconstruct),
+  `Simulation.input_port()` describes a simulation's entrance and `with_input` takes a
+  launch bound to it, recording `configuration["coupling"]` and drawing no new noise.
+  Output schema 24 records each run's plane-reference record (`RunMetadata.reference`).
+- **Coupling models**
+  ([SEP 31](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0031-simulation-coupling.html),
+  phase 3). `couple(plane, port, model=CouplingModel(kind, model_error=...))` is the one
+  path from a field plane to a launch bound to a port, returning the launch and an
+  immutable `CouplingReport`. `same_basis` copies an identical basis, applies a declared
+  energy-preserving `BasisChange` or recovers a general modal plane by the flux pairing;
+  `scalar_paraxial` fits Gaussian, analytic or sampled beams into a capillary's HE1m
+  modes, one capillary's exit into another of any radius, and one weakly guiding
+  step-index fibre into another, in the common paraxial measure; `vector_paraxial`
+  couples into a general modal guide with the forward H closure. Each is admitted
+  against its energy budget: angular tails, the weak-guidance contrast screen or a
+  recorded pair envelope (`CAPILLARY_ENVELOPE`, `STEP_INDEX_ENVELOPE`), metric defects,
+  the H closure, a passive-map certificate and numerical errors; uncaptured energy is
+  reported only where a common positive metric exists. `FieldPlane.from_analytic`
+  samples an analytic field with its support and domain checks, `FieldPlane.from_pulse`
+  takes a reference `index=`, `field_plane(run, source=...)` carries an ordinary mode
+  set's scalar profiles (`ScalarModeBasis`), and `Outcouple` synthesises a guide's exit
+  field on a spatial grid under a declared interface model. Ports state the models they
+  admit. The phase-2 `same_basis` function is removed in favour of `couple`.
+- **Transport between planes**
+  ([SEP 31](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0031-simulation-coupling.html),
+  phase 4). `coupling.transport` carries a radial or Cartesian `FieldPlane` through an
+  ordered sequence of linear elements -- `FreeSpace` (exact angular-spectrum
+  propagation, with an explicit `"angular"` or `"fresnel"` output plane), `ThinLens`,
+  `Aperture`, `TransmissionMask`, `Alignment`, `PolarisationTransform`, `Mirror`,
+  `PlanarInterface` and `SpectralTransfer` (any `optics` transfer function or `Chain`)
+  -- and returns the plane with its reference, geometry, medium, metric and provenance
+  updated and a sequential ledger in joules. Thin screens carry their angular-flux
+  certificate; undersampled phases, wrapped rays and evanescent content are refused
+  unless their removal is declared, and a same-grid field filling the window's outer
+  band is refused beyond `FreeSpace(edge_tolerance=...)` (default 1e-4). Refusals raise `CouplingError`.
+- **Coupled workflows**
+  ([SEP 31](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0031-simulation-coupling.html),
+  phase 5). The eight compositions of the coupling chapter -- capillary into capillary,
+  a nonlinear gas gap into a capillary, fibre into fibre, Gaussian, analytic and
+  Cartesian beams into a guide, a guide's far field, and SPM, compression and relay
+  optics into a second capillary -- run as short integrated tests that assert their
+  energy ledgers, with sources and receivers on different CPU backends. A plane's path
+  certificate (`FieldPlane.certificate`, `CouplingReport.certificate`,
+  `TransportReport.source_certificate`) is the rebuilt `AdiabaticAdmission`, not its raw
+  record. `CAPILLARY_ENVELOPE` now bounds the scalar model against Marcatili's leaky core
+  field (bound 6e-3 at its range's top, delta = 1e-2, scaled by the pair's delta) rather
+  than against the scalar profile itself; bins outside an envelope's range, including a
+  fibre's V across the band, are counted in full; the modal overlap quadrature enters
+  the budget as `2 delta + delta^2`. `scalar_paraxial` also admits a radial or
+  Cartesian beam into a weakly guiding step-index fibre (LP01, V 1.5 to 2.4, contrast
+  to 0.01) within `STEP_INDEX_BEAM_ENVELOPE`, the scalar overlap against the beam's
+  full-vector flux coupling into the exact HE11 pair maximised over every field in the
+  admitted cone (bound 1e-2 at contrast 0.01, scaled by the fibre's contrast).
+  `same_basis`'s flux recovery of a general modal plane allows the plane's own metric
+  defect as well as the port's when it checks that the field lies in the port's span,
+  and reports both.
+  the budget as `2 delta + delta^2`.
+  `VECTOR_STEP_INDEX_ENVELOPE` bounds `vector_paraxial` into a step-index guide
+  against an independent full-vector mode-matching solution of the entrance facet,
+  maximised over every incident field in the admitted cone (bound 3.0e-3 at contrast
+  0.05, twice the Fresnel ceiling a mode near cutoff approaches, V 1.5 to 8, scaled by
+  the squared contrast); its item is counted and a guide outside its range is refused
+  by name. A step-index
+  port carries `InputPort.normalised_frequency`; a graded-index guide keeps an
+  uncounted item without a value.
 - **Media and responses.**
   - Gases, gas mixtures, glasses and metals from the [optmat](https://github.com/LupoLab/optmat)
     material library.
@@ -73,6 +155,11 @@ The first public release. It contains:
     ([SEP 29](https://solprop.readthedocs.io/en/latest/dev/seps/archive/sep-0029-compiled-backend-distribution.html)).
   - Each backend is tested against the reference implementation within derived error
     bounds.
+  - A short start-up: a run on the native backend imports neither Numba nor
+    `scipy.signal`, plotting imports `matplotlib.pyplot` only when it draws, and an
+    optmat rate builds only the model it uses (optmat 0.9.1, which reads only the data a
+    model needs). A five-centimetre capillary run with ionisation is under way in about
+    3 s on an Apple M5 Max, from 5.5 s.
 - **The native backend.**
   - `NativeBackend` runs one trial step per native call, with states, views and FFT
     plans resident in the execution space; `NativeBatchBackend` runs fixed-schedule

benchmarks/guides.py

@@ -21,6 +21,7 @@
 from benchmarks.records import SuiteError
 from solprop.boundaries import absorber
 from solprop.constants import C
+from solprop.coupling import CouplingModel
 from solprop.driver import Simulation
 from solprop.grid import FieldGrid
 from solprop.modes import (
@@ -37,6 +38,7 @@
 from solprop.modes.material import JsonValue
 from solprop.physdata import fused_silica
 from solprop.profiles import PiecewiseLinear
+from solprop.pulses import GaussianPulse, SpatialPulse
 
 __all__ = ["ScaledPermittivity", "advanced", "coupled", "grin", "moving", "step_index"]
 
@@ -222,17 +224,24 @@ def grin(*, nonlinear: bool) -> Simulation:
             / C
         )
         period = 2 * np.pi / float(np.mean(-np.diff(beta)))
-        beam = np.zeros((nodes.xy.shape[0], 3))
-        beam[:, 0] = np.exp(-((np.hypot(nodes.xy[:, 0], nodes.xy[:, 1]) / 12e-6) ** 2))
+        # The incident beam's energy is over its whole plane; the channels launch
+        # the share they capture, coupled under the vector paraxial model.
+        beam = SpatialPulse(
+            GaussianPulse(
+                wavelength=wavelength,
+                fwhm=300e-15,
+                energy=5e5 * 300e-15 * np.sqrt(np.pi / (4 * np.log(2))),
+            ),
+            12e-6,
+        )
         return Simulation.from_waveguide(
             (),
             0.1,
             provider=guide,
             grid=grid,
-            transverse=beam,
+            incident=beam,
+            coupling=CouplingModel("vector_paraxial", model_error=0.2),
             lambda0=wavelength,
-            fwhm=300e-15,
-            energy=5e5 * 300e-15 * np.sqrt(np.pi / (4 * np.log(2))),
             noise="input",
             seed=41,
             dz_max=period / 10,

docs/api/index.md

@@ -46,7 +46,8 @@ In scripts and library code, import from the home modules listed below.
 | module | what it holds |
 |---|---|
 | {mod}`solprop.output` | the in-memory and HDF5 output handlers, the run's metadata record, `open_file` and resuming a run, live snapshots (`SnapshotController`, `read_snapshot`, `restore_snapshot`; [the output page](../guide/results/output.md)), and the raw TDSE response archive (`TDSEArchive`, `open_tdse_archive`; [the TDSE response](../guide/media/tdse.md#the-raw-response-archive)) |
-| {mod}`solprop.processing` | post-processing of a saved run: fields, spectra, pulse metrics, coherence, compression, and the physical fields of a general modal run |
+| {mod}`solprop.processing` | post-processing of a saved run: fields, spectra, pulse metrics, coherence, compression, the physical fields of a general modal run, and `field_plane`, a saved plane read back for coupling |
+| {mod}`solprop.coupling` | coupling simulations through a field plane: `FieldPlane` (from a run, a `SpatialPulse`, an analytic field or arrays), `regrid`, `InputPort`, `couple` under a `CouplingModel` with its `CouplingReport`, the scalar profiles `ScalarModeBasis`, the recorded pair envelopes and `Outcouple`; `transport` through the linear elements `FreeSpace`, `ThinLens`, `Aperture`, `TransmissionMask`, `Alignment`, `PolarisationTransform`, `Mirror`, `PlanarInterface` and `SpectralTransfer` ([coupling simulations](../guide/workflows/coupling.md); [the transport report](transport.md)) |
 | {mod}`solprop.stats` | the statistics recorded at the saved planes, and `StatsSpec` to choose them |
 | {mod}`solprop.plotting` | the standard figures: propagation maps, slices, spectrograms, statistics |
 | {mod}`solprop.optics` | linear optics applied to a pulse outside a propagation: materials, chirped mirrors, grating and prism pairs |
@@ -73,6 +74,7 @@ design behind both is in the [developer documentation](../dev/index.md).
 species
 tabulated
 scans
+transport
 ```
 
 ## Complete generated reference

docs/api/transport.md

@@ -0,0 +1,19 @@
+# Transport between planes
+
+{func}`solprop.coupling.transport` carries a radial or Cartesian
+{class}`~solprop.coupling.plane.FieldPlane` through an ordered sequence of the linear
+elements of {mod}`solprop.coupling.elements` and returns the transported plane with its
+{class}`~solprop.coupling.transport.TransportReport`, the sequential ledger in joules
+([transporting a plane](../guide/workflows/coupling.md#transporting-a-plane-between-planes)).
+
+Because the function has the same name as its module, `solprop.coupling.transport`
+refers to the function, not the module; the module's report class is documented on this
+page. Both names are importable from {mod}`solprop.coupling`.
+
+```{eval-rst}
+.. autoclass:: solprop.coupling.transport.TransportReport
+   :members:
+```
+
+Transport between planes was proposed and carried out by
+[SEP 31](../dev/seps/archive/sep-0031-simulation-coupling.md).