solprop.stats.definitions#

The reference definition of each plane statistic, on internal spectra.

Every definition is written once, on internal FFT-convention arrays of shape (n_modes, n_pol, n_omega), reduces in a fixed order and is what a backend’s fused pass is validated against; an undefined value is nan, a missing dependency an solprop.exceptions.OutputError.

Module Attributes

DEFAULT_ZDW_RANGE

Search window of zdw() when no narrower one is given, m.

Functions

analytic_field(grid, field)

Return the time-domain analytic signal of a stored spectrum.

analytic_flux(grid, field, *[, metric])

Return the peak of the plane's same-frequency analytic flux, in watts.

energy(grid, field)

Return the pulse energy of each mode and polarisation, in joules.

energy_window(grid, field, windows)

Return the energy inside each spectral window, in joules.

fwhm_t(grid, field, *[, metric])

Return the width of the central feature at half maximum, in seconds.

fwhm_t_outer(grid, field, *[, metric])

Return the total extent above half maximum, in seconds.

inband_wavelengths(grid)

Return the shortest and longest in-band wavelength of a grid, in metres.

omega0(grid, field, *[, metric])

Return the centroid of the spectral energy density, per mode and polarisation.

peak_power(grid, field)

Return the largest instantaneous power each mode reaches, in watts.

peak_power_total(grid, field)

Return the largest instantaneous power of the whole field, in watts.

peak_power_window(grid, field, windows)

Return the peak power of each mode inside each spectral window, in watts.

physical_energy(grid, field, *[, metric])

Return the physical energy through the plane, in joules.

profile_value(profile, z)

Return the value of a z-profile at one position.

species_statistics(densities, fractions, ...)

Reduce species populations at the node of largest total electron density.

spectral_flux(grid, field, *[, metric])

Return the physical energy's spectral density, in J/(rad/s).

zdw(modes, z, *[, wavelength_limits])

Return the zero-dispersion wavelength of each mode at one position.

solprop.stats.definitions.DEFAULT_ZDW_RANGE = (1e-07, 3e-06)#

Search window of zdw() when no narrower one is given, m.

solprop.stats.definitions.analytic_field(grid, field)[source]#

Return the time-domain analytic signal of a stored spectrum.

The one construction of the analytic signal in the package, so that the statistics, the backends’ on-axis intensity and anything else that needs a power agree by construction. It serves both grids: an envelope grid’s state already is the analytic signal with the carrier removed, so it only has to be transformed back; a field grid’s is the analytic signal of the real field. solprop.fourier.analytic_signal() neither doubles the zero-frequency bin nor discards the Nyquist bin, because only that convention makes the real part an identity and the two energy functionals an exact Parseval pair.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

Stored spectrum, shape (..., n_omega), internal convention.

Returns:
numpy.ndarray

Complex analytic signal, shape (..., n_t), whose modulus squared is the instantaneous power in watts.

solprop.stats.definitions.analytic_flux(grid, field, *, metric=None)[source]#

Return the peak of the plane’s same-frequency analytic flux, in watts.

The general modal basis’s name for a peak power: max_t sum_m |a_m(t)|^2, the same-frequency diagonal of the Poynting flux, which is all a modal state can say about a power on its own.

It is not the cross-section flux, and the difference is physics. The physical int Re(E_a x conj(H_a))/2 . z dA of the reconstructed fields carries the guide’s cross-frequency flux kernel K_ij = sum_q w_q [e_x(w_i) conj(h_y(w_j)) - e_y(w_i) conj(h_x(w_j))]/2, whose diagonal a provider normalises to one and whose off-diagonal it says nothing about. The two peaks therefore differ, bounded term by term by sum_ij |B_i||B_j||K_ij - 1| and measured at 1.3e-5 of the peak on the general-basis test fixture, inside a bound of 3.4e-5: even a positive spectral metric does not make an instantaneous cross-frequency flux a sum of coordinate powers. The time integrals do agree, to 5.0e-7 there, because the cross-frequency terms are an integer number of cycles in the window. For the flux itself, reconstructed from the guide’s stored reference, use solprop.processing.modal.reconstructed_flux(), a trace in time whose peak is this statistic plus the cross-frequency terms; its real-field partner with the sum-frequency term is solprop.processing.modal.instantaneous_flux().

The arithmetic is exactly ``peak_power_total``’s on the identity metric, which is what metric=None evaluates, bit for bit. With a metric it is the same peak taken on the whitened amplitudes c = W^(1/2) a of _whitened, so that the quantity peaked is the physical same-frequency flux sum_mn conj(a_m) W_mn a_n and not a sum of coordinate powers. The old name is refused on this basis rather than redefined: peak_power_total promises that sum of coordinate powers, and on a basis that is not orthonormal there is no such sum to promise.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

Stored spectrum, shape (n_modes, n_pol, n_omega), internal convention, in the square root of watts.

metricnumpy.ndarray or None, optional

The basis flux metric W(omega), shape (n_modes, n_modes, n_omega), dimensionless; None, the default, is the identity.

Returns:
numpy.ndarray

Peak same-frequency analytic flux, a zero-dimensional array, W.

Raises:
solprop.exceptions.OutputError

If metric disagrees in shape with field, or is not positive definite at some frequency, so that no orthonormal basis exists to measure in.

Examples

>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import analytic_flux, peak_power_total
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, peak_power=1e9)
>>> built = pulse.build(grid)
>>> bool(analytic_flux(grid, built) == peak_power_total(grid, built))
True
solprop.stats.definitions.energy(grid, field)[source]#

Return the pulse energy of each mode and polarisation, in joules.

This is solprop.fourier.energy_omega(), the exact discrete form of docs/dev/conventions.md §4, which agrees with the time-domain functional to round-off. No quadrature weights (such as an extended Simpson rule on a field grid) are derived: those would differ from this by their fourth-order quadrature error.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

Stored spectrum, shape (n_modes, n_pol, n_omega), internal convention, in the square root of watts.

Returns:
numpy.ndarray

Energy, shape (n_modes, n_pol), J.

Examples

>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import energy
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6)
>>> f"{float(energy(grid, pulse.build(grid))[0, 0]):.6e}"
'1.000000e-06'
solprop.stats.definitions.energy_window(grid, field, windows)[source]#

Return the energy inside each spectral window, in joules.

The gate is hard and half-open, lo <= omega < hi, so windows that tile the band partition the bins and their energies sum to the total exactly.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

windowsnumpy.ndarray

Window edges, shape (n_windows, 2), rad/s, each row (lo, hi). Convert a wavelength pair with omega = 2 pi c / wavelength, remembering that it reverses the order.

Returns:
numpy.ndarray

Energy per window, shape (n_windows, n_modes, n_pol), J.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import energy, energy_window
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> built = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6).build(grid)
>>> tiling = np.array([[-np.inf, 2.4e15], [2.4e15, np.inf]])
>>> total = energy_window(grid, built, tiling).sum()
>>> bool(np.isclose(total, energy(grid, built).sum(), rtol=1e-15))
True
solprop.stats.definitions.fwhm_t(grid, field, *, metric=None)[source]#

Return the width of the central feature at half maximum, in seconds.

The total power sum_modes sum_pol |E_a(t)|^2 is formed, the half-maximum level taken from its global peak with no baseline subtraction, and the crossings found by walking outwards from that peak to the first sample below the level on either side and interpolating linearly. Structure further out – a dispersive wave, a soliton that has walked off, a noise pedestal – does not widen the answer, which is why this is the number to read as a pulse duration. Use fwhm_t_outer() for the total extent above half maximum.

On a basis whose flux Gram is not the identity this takes the metric: the trace whose width is measured is then the physical same-frequency flux analytic_flux() peaks, evaluated on the whitened amplitudes of _whitened, so that a run does not report the width of a quantity whose peak it does not report.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

metricnumpy.ndarray or None, optional

The basis flux metric W(omega), shape (n_modes, n_modes, n_omega), dimensionless; None, the default, is the identity.

Returns:
numpy.ndarray

The width as a zero-dimensional array, s. A trace that never falls to half its maximum – a continuous wave, an empty plane – has no width and gives nan.

Raises:
solprop.exceptions.OutputError

If metric disagrees in shape with field, or is not positive definite at some frequency, so that no orthonormal basis exists to measure in.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import fwhm_t
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> built = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6).build(grid)
>>> bool(np.isclose(fwhm_t(grid, built), 30e-15, rtol=1e-4))
True
solprop.stats.definitions.fwhm_t_outer(grid, field, *, metric=None)[source]#

Return the total extent above half maximum, in seconds.

The first and the last sample anywhere in the window that exceed half the peak power, interpolated outwards. On a clean single pulse this equals fwhm_t(); on a structured trace it spans every satellite, so the pair together says how much of the energy sits outside the central feature.

It takes the metric for the reason fwhm_t() does.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

metricnumpy.ndarray or None, optional

The basis flux metric W(omega), shape (n_modes, n_modes, n_omega), dimensionless; None, the default, is the identity.

Returns:
numpy.ndarray

The extent as a zero-dimensional array, s, or nan when the trace reaches the edge of the window still above half its maximum, or carries no power.

Raises:
solprop.exceptions.OutputError

If metric disagrees in shape with field, or is not positive definite at some frequency, so that no orthonormal basis exists to measure in.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import fwhm_t, fwhm_t_outer
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> built = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6).build(grid)
>>> bool(np.isclose(fwhm_t_outer(grid, built), fwhm_t(grid, built), rtol=1e-12))
True
solprop.stats.definitions.inband_wavelengths(grid)[source]#

Return the shortest and longest in-band wavelength of a grid, in metres.

The search window zdw() uses by default when collect() calls it: a zero-dispersion point outside the simulated band says nothing about the run, and hunting for one there drives every material model into extrapolation.

Parameters:
gridsolprop.grid.TimeGrid

The grid.

Returns:
tuple of float

(shortest, longest) in m, from the grid’s in-band frequency limits.

Examples

>>> from solprop.grid import EnvelopeGrid
>>> from solprop.stats import inband_wavelengths
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> [f"{value * 1e9:.1f}" for value in inband_wavelengths(grid)]
['400.0', '2000.0']
solprop.stats.definitions.omega0(grid, field, *, metric=None)[source]#

Return the centroid of the spectral energy density, per mode and polarisation.

\[\omega_0 = \frac{\sum_k \omega_k\,S(\omega_k)}{\sum_k S(\omega_k)}\]

with \(S\) from solprop.fourier.spectral_density(). The prefactor of the density cancels in the ratio, so this is the first moment of \(|\tilde E|^2\) over the frequency axis. The sum runs over every bin, including the zero-frequency one: outside the active band a propagated state is identically zero, so the bins there contribute nothing.

Because the centroid is an energy-weighted mean, the whole field’s centroid is the energy-weighted mean of these, which is why the statistic is per column rather than summed.

On a basis whose flux Gram is not the identity this takes the metric, and the columns are then the whitened ones of _whitened: a coordinate column of a nonorthogonal basis carries no separable spectral energy at all – the columns interfere – so a centroid of |a_m(omega)|^2 would be a promise the basis cannot keep. W^(1/2) is the identity plus half the basis’s Gram departure, so on a unitary change of basis of a certified orthonormal reference, which is the only kind this package executes, the whitened column is the declared channel to within that departure and the centroid moves by no more.

An empty column is empty relative to the plane. A column whose density sums to at most one machine epsilon of the largest column’s has no centroid and is nan. That floor is relative rather than exactly zero because whitening mixes: the unlaunched partner of a launched circular channel carries W^(1/2) times the other’s amplitude – 1e-32 of it on this route’s own fixture – and an exact-zero test would report a finite centroid of the whitening’s rounding noise for a channel nothing was launched into.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

metricnumpy.ndarray or None, optional

The basis flux metric W(omega), shape (n_modes, n_modes, n_omega), dimensionless; None, the default, is the identity and is the bitwise unchanged path.

Returns:
numpy.ndarray

Centroid frequency, shape (n_modes, n_pol), rad/s. A column carrying no energy has no centroid and is nan.

Raises:
solprop.exceptions.OutputError

If metric disagrees in shape with field, or is not positive definite at some frequency, so that no orthonormal basis exists to measure in.

Examples

>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import omega0
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6)
>>> f"{float(omega0(grid, pulse.build(grid))[0, 0]):.6e}"
'2.354564e+15'
solprop.stats.definitions.peak_power(grid, field)[source]#

Return the largest instantaneous power each mode reaches, in watts.

max_t sum_pol |E_a(t)|^2: the polarisation components of one mode are summed before the maximum is taken, because they are two components of one field and their powers add at each instant. The analytic signal is formed once for the whole call. This array function measures squared true-power amplitude; run statistics use analytic Poynting flux, with the arithmetic-mean frequency kernel instead.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

Returns:
numpy.ndarray

Peak power, shape (n_modes,), W.

Examples

>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import peak_power
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, peak_power=1e9)
>>> f"{float(peak_power(grid, pulse.build(grid))[0]):.6e}"
'1.000000e+09'
solprop.stats.definitions.peak_power_total(grid, field)[source]#

Return the largest instantaneous power of the whole field, in watts.

max_t sum_modes sum_pol |E_a(t)|^2: the modes are summed before the maximum, so this is the peak of the total power and not the largest of the per-mode peaks, which arrive at different times.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

Returns:
numpy.ndarray

Peak total power, a zero-dimensional array, W.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import peak_power, peak_power_total
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, peak_power=1e9)
>>> built = pulse.build(grid)
>>> f"{float(peak_power_total(grid, built)):.6e}"
'1.000000e+09'
solprop.stats.definitions.peak_power_window(grid, field, windows)[source]#

Return the peak power of each mode inside each spectral window, in watts.

The spectrum is gated with the same hard half-open window as energy_window() and transformed back, so this is the peak power of the light in that band. One scalar per mode per window.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

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

windowsnumpy.ndarray

Window edges, shape (n_windows, 2), rad/s, each row (lo, hi).

Returns:
numpy.ndarray

Peak power, shape (n_windows, n_modes), W.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import peak_power_window
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, peak_power=1e9)
>>> built = pulse.build(grid)
>>> whole = np.array([[-np.inf, np.inf]])
>>> f"{float(peak_power_window(grid, built, whole)[0, 0]):.6e}"
'1.000000e+09'
solprop.stats.definitions.physical_energy(grid, field, *, metric=None)[source]#

Return the physical energy through the plane, in joules.

The general modal basis’s name for an energy, and the one number of that family that survives a change of coordinates: the same-frequency product of the state with the basis’s flux metric, sum_k sum_mn conj(a_m) W_mn a_n, integrated over frequency. A coordinate energy is not additive when W is not the identity, and this total is, which is why it is a scalar and energy is an array.

On the identity metric this is exactly ``sum(energy(grid, field))``, which is what metric=None evaluates, bit for bit. With a metric it is the same functional of the whitened amplitudes c = W^(1/2) a of _whitened, which is the definition above and not a second one: sum_m |c_m|^2 = sum_mn conj(a_m) W_mn a_n at every frequency, and the frequency integral is the Parseval weight of docs/dev/conventions.md section 4 either way.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

Stored spectrum, shape (n_modes, n_pol, n_omega), internal convention, in the square root of watts.

metricnumpy.ndarray or None, optional

The basis flux metric W(omega), shape (n_modes, n_modes, n_omega), dimensionless; None, the default, is the identity.

Returns:
numpy.ndarray

Physical energy, a zero-dimensional array, J.

Raises:
solprop.exceptions.OutputError

If metric disagrees in shape with field, or is not positive definite at some frequency, so that no orthonormal basis exists to measure in.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import energy, physical_energy
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> built = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6).build(grid)
>>> bool(physical_energy(grid, built) == energy(grid, built).sum())
True
solprop.stats.definitions.profile_value(profile, z)[source]#

Return the value of a z-profile at one position.

The one implementation behind the density, pressure and core_radius statistics, which differ only in which profile they read; the catalogue gives each its own units.

Parameters:
profilesolprop.profiles.ZProfile

The path along the waveguide.

zfloat

Position, m.

Returns:
numpy.ndarray

The value as a zero-dimensional array, in the profile’s own units. Those are SI except for a pressure path, which is in bar: pressures are the one documented exception at the user interface (docs/dev/conventions.md §1) and a solprop.profiles.PressureGradient is a user-interface object.

Examples

>>> from solprop.profiles import PressureGradient
>>> from solprop.stats import profile_value
>>> gradient = PressureGradient.two_point(1.0, 2.0, 0.0)
>>> f"{float(profile_value(gradient, 0.75)):.6f}"
'1.000000'
solprop.stats.definitions.species_statistics(densities, fractions, peak_rates, potentials, weights)[source]#

Reduce species populations at the node of largest total electron density.

Parameters:
densitiesnumpy.ndarray

Component number densities in m^-3, in mixture order.

fractionsnumpy.ndarray

Final ionised fractions at each node, shape (n_species, n_nodes). Components without an ionisation channel have zero entries.

peak_ratesnumpy.ndarray

Largest rate over all nodes per species in s^-1; cycle-averaged on envelope grids.

potentialsnumpy.ndarray

Ionisation potentials in J, zero for components without channels.

weightsnumpy.ndarray

Physical transverse quadrature weights in m². The mode-averaged case uses its effective area as its single weight.

Returns:
dict

The five species statistics plus total electron density and peak rate. species_ionisation_energy is final ionised inventory in J/m, including preionisation. Pulse-deposited ionisation work counts only newly freed electrons and must subtract the initial fractions before this reduction.

Raises:
OutputError

If a population, rate, potential or quadrature weight is outside its domain.

solprop.stats.definitions.spectral_flux(grid, field, *, metric=None)[source]#

Return the physical energy’s spectral density, in J/(rad/s).

The spectrum analogue of physical_energy(), and the one array of the general modal family: the same same-frequency product of the state with the basis’s flux metric, sum_mn conj(a_m) W_mn a_n, published per bin instead of integrated over frequency. It is a density in the sense of docs/dev/conventions.md section 4 – dU/domega, the prefactor that pairs with the shot-noise amplitude so that one photon in a bin gives S(omega_k) domega = hbar omega_k – and it is solprop.fourier.spectral_density() summed over the channel axis, which is what makes it additive where a coordinate spectrum is not.

It is indexed by frequency and by nothing else. A per-channel spectral energy is no more additive than a per-channel energy on a basis whose Gram is not the identity, so the channel axis is summed after the whitening and not published.

The frequency sum is ``physical_energy``, exactly on every interior bin: domega times this density is the 4 dt / n_t weight of solprop.fourier.energy_omega() there. The zero-frequency and Nyquist bins are the documented exception – the analytic signal does not double them, so summing the density over every bin overcounts those two – and both are identically zero on any grid solprop.grid builds, whose spectral collar apodises them away. Ask physical_energy() when an exact energy is wanted.

Parameters:
gridsolprop.grid.TimeGrid

The grid the spectrum lives on.

fieldnumpy.ndarray

Stored spectrum, shape (n_modes, n_pol, n_omega), internal convention, in the square root of watts.

metricnumpy.ndarray or None, optional

The basis flux metric W(omega), shape (n_modes, n_modes, n_omega), dimensionless; None, the default, is the identity.

Returns:
numpy.ndarray

Spectral energy density, shape (n_omega,), J/(rad/s).

Raises:
solprop.exceptions.OutputError

If metric disagrees in shape with field, or is not positive definite at some frequency, so that no orthonormal basis exists to measure in.

Examples

>>> import numpy as np
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> from solprop.stats import physical_energy, spectral_flux
>>> grid = EnvelopeGrid.from_limits(1.0, 800e-9, (400e-9, 2e-6), 1e-12)
>>> built = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6).build(grid)
>>> density = spectral_flux(grid, built)
>>> density.shape == (grid.n_omega,)
True
>>> total = float(np.sum(density) * grid.d_omega)
>>> bool(np.isclose(total, float(physical_energy(grid, built)), rtol=1e-14))
True
solprop.stats.definitions.zdw(modes, z, *, wavelength_limits=(1e-07, 3e-06))[source]#

Return the zero-dispersion wavelength of each mode at one position.

Off by default: it is a root search on beta_2 per mode, which is slow and does not belong on every accepted step. Each call stands alone: no previous answer is carried over as the next search’s starting guess, so one failure cannot poison every later plane with nan.

Parameters:
modescollections.abc.Sequence

The propagated modes, in state order.

zfloat

Position along the waveguide, m.

wavelength_limitstuple of float, optional

Shortest and longest wavelength in m to bracket the root in. Defaults to a 100 nm to 3 um window; collect() narrows it to the grid’s own band with inband_wavelengths(), which is where the answer means anything and where the material models are not extrapolating.

Returns:
numpy.ndarray

Zero-dispersion wavelength, shape (n_modes,), m.

Raises:
solprop.exceptions.NoZeroDispersionError

If a mode has no zero-dispersion point in the search window, rather than a missing value that would propagate silently. collect() records nan with a warning instead, so that a run is not stopped by its band.

Examples

>>> from solprop.modes import MarcatiliMode
>>> from solprop.stats import zdw
>>> mode = MarcatiliMode(125e-6, "He", 0.4, model="reduced", cladding=1.45)
>>> f"{zdw([mode], 0.0, wavelength_limits=(150e-9, 900e-9))[0] * 1e9:.1f}"
'376.7'