Reading the output of a modal run#
Every run returns an output handler — in memory, or an HDF5 file with output= — and
everything is read from it through the accessors of solprop.processing and the
figures of solprop.plotting, exactly as for any other run (analysing a
run, output). This
chapter covers what is different about a capillary with a coherent wall and about the
general modal route: which quantities a basis defines, what the record holds, and how the
physical fields are rebuilt. A saved plane read as a field plane, with its reference,
metric and provenance, for transport or for launching another run, is
field_plane() (coupling simulations).
A capillary with a coherent wall#
Nothing changes. The coupled flow couples the modes; it does not change the basis the
state is written in, so each saved channel is still a Marcatili mode’s true-power
amplitude, and every ordinary accessor — energy per mode, peak_power, fwhm_t,
get_spectral_density, the propagation maps — reads it as on any modal run. On a taper each
mode’s amplitude carries that mode’s own normalisation at every position, so a mode’s
energy is that mode’s energy there. What the wall adds is the record’s flow entry
(the capillary chapter).
The general modal route#
A general modal run’s state is a set of channel amplitudes in √W, one per channel of the guide, normalised to unit Poynting flux. On the provider’s own basis they are orthonormal in true power; on a declared basis (a circular pair, a rotated split block) they are not orthogonal in the same sense, and the basis carries a dense metric \(W\). Two consequences decide what a run reports.
The statistics are the physical ones, and they are scalars. physical_energy is the
energy in the physical field, \(\int \mathbf a^{\mathsf H}W\mathbf a\,d\omega\) summed
over the channels; analytic_flux is the peak over time of the flux built from the
same pairing of each frequency with itself; spectral_flux, requested by name, is the
spectral density of physical_energy, in J/(rad/s). On the
provider’s own basis these are exactly sum(energy) and peak_power_total; on a
declared one they are what those would have to become. The names that promise a
per-channel energy or power (energy, peak_power, peak_power_total,
energy_window, peak_power_window, peak_intensity) are refused by name on this
route, each with its replacement, rather than redefined; quadrature_error is refused
too, because a provider’s node rule has no embedded coarse rule to compare with — there
is no automatic transverse-resolution alarm during a general modal run. fwhm_t,
fwhm_t_outer and omega0 stay, taking the metric. zdw stays, except beside a split
block, which has no per-channel propagation constant.
import numpy as np
from solprop.driver import prop_waveguide
from solprop.exceptions import OutputError
from solprop.grid import FieldGrid
from solprop.modes import (
IndexMaterial,
MaterialKerr,
MaterialRegion,
ModalGuide,
StepIndexMode,
)
from solprop.processing import get_spectral_density
from solprop.processing import energy as energy_per_mode
from solprop.processing.modal import (
electric_field,
physical_energy,
reconstructed_flux,
reference_tables,
)
from solprop.stats import StatsSpec
core, cladding = IndexMaterial(1.45), IndexMaterial(1.44)
pair = [
StepIndexMode(6e-6, core=1.45, cladding=1.44, profile_wavelength=835e-9, parity=p)
for p in ("even", "odd")
]
regions = (
MaterialRegion("core", 0.0, 6e-6, core, (MaterialKerr(n2=2.6e-20, at=835e-9),)),
MaterialRegion("cladding", 6e-6, None, cladding),
)
provider = ModalGuide.from_step_index(
pair, core=core, cladding=cladding, regions=regions
).field_provider
grid = FieldGrid.from_limits(1e-3, 835e-9, (790e-9, 890e-9), 200e-15)
active = grid.omega[grid.active_mask]
low = 0.99 * float(active[0])
guide = ModalGuide.from_provider(
provider,
np.linspace(low, 1.01 * float(active[-1]), 25),
nodes=provider.node_rule(low, n_r=24),
degenerate_blocks=((0, 1),),
)
run = prop_waveguide(
(),
1e-3,
provider=guide,
grid=grid,
wavelength=835e-9,
fwhm=40e-15,
energy=1e-9,
n_save=3,
dz_max=1e-4,
dz_init=1e-4,
progress="none",
stats=StatsSpec(names=("physical_energy", "analytic_flux", "spectral_flux")),
)
print(run.metadata.modal["accessors"])
print("physical energy (J):", physical_energy(run))
try:
energy_per_mode(run)
except OutputError as refusal:
print("refused:", str(refusal)[:100], "...")
The spectra are read as for any run — get_spectral_density sums the channels’ true-power
spectral densities:
wavelength, density = get_spectral_density(run, "wavelength", plane=-1, modes="sum")
print(f"spectral peak at {wavelength[np.argmax(density)] * 1e9:.1f} nm")
The file holds amplitudes, not fields. The run’s record names the guide — the
provider, the sampling, the materials and their responses, the channel labels row by row,
the table and metric identities with their measured Gram departures, and the basis — but
not its tens of megabytes of stored E and H. The physical fields are rebuilt from the
guide: every reconstruction accessor takes the guide the run was made with, rebuilds the
run’s own reference tables from it, and checks both against the identity the file
carries, path by path, before it reads anything. Each reads one saved plane, the last
unless plane= or z= names another:
field = electric_field(run, guide=guide) # V/m, (nodes, 3, t)
flux = reconstructed_flux(run, guide=guide) # W, (t,)
density = reconstructed_flux(run, guide=guide, density=True) # W/m^2, (nodes, t)
print(field.shape, f"peak flux {flux.max():.3e} W")
print(f"peak flux density {density.max() * 1e-4:.3e} W/cm^2")
The rebuild takes tens of milliseconds, more if the guide has still to be solved. A loop
over many planes rebuilds the tables once with
reference_tables() and passes them to each call:
tables = reference_tables(run, guide=guide)
peaks = [
reconstructed_flux(run, guide=guide, tables=tables, plane=i).max()
for i in range(run.n_saved)
]
print("peak flux at each plane (W):", np.round(peaks, 4))
reconstructed_flux is the flux of the reconstructed fields, a trace in time, which
carries the guide’s cross-frequency flux kernel as well; the run’s own analytic_flux
statistic is the peak of the same-frequency one, and the two peaks differ by at most
\(\sum_{ij}|B_i||B_j||K_{ij}-1|\), where \(K_{ij}\) is the guide’s flux kernel between
frequencies \(\omega_i\) and \(\omega_j\), one on its diagonal (measured: 1.3e-5 of the peak
on a strongly guiding strand). Their time integrals agree to far better than that,
because the cross-frequency terms integrate away. instantaneous_flux (the real fields’
flux, with its sum-frequency term), magnetic_field and coordinate_intensity (the
flux density each channel would carry alone, which is not additive) are the others,
and plane_nodes returns the node positions and area weights they are all given on;
output and
statistics have the definitions.
What the file’s key protects. A general modal file resumes only against the same guide, table, materials, channel order and basis — every one of them is in the resume key — and a reconstruction is refused against a guide that is not the one the file names. Keep the script that builds the guide beside the file:
from solprop.output import open_file
run.to_file("fibre.h5")
with open_file("fibre.h5") as saved:
again = reconstructed_flux(saved, guide=guide)
print("the same flux from the file:", bool(np.allclose(again, flux)))