solprop.processing.modal#

Physical E and H on a saved plane of a general modal run, and what they measure.

A general modal file stores channel amplitudes on a coordinate axis, not a physical field, and records the guide’s identity rather than its E/H reference arrays. This module is the way back: reference_tables() rebuilds the run’s reference tables from the guide (guide= is required everywhere; tables= reuses one rebuild), checking the tables, the guide’s sampling and its regions against the stored identity path by path, and refusing the first entry that disagrees.

These names are admitted on a general modal basis and refused on every other (solprop.output.capability). The manual covers this in docs/guide/results/reading-output.md and docs/guide/results/resuming.md (“Reading E and H back”).

Functions

channel_amplitudes(electric, magnetic, tables)

Recover channel amplitudes from a nodal E/H pair, in the square root of watts.

channel_labels(output)

Return the ordered channel labels a file records for its mode axis.

coordinate_intensity(output, *, guide[, ...])

Return the flux density each channel would carry alone, in W/m^2.

electric_field(output, *, guide[, tables, ...])

Return the electric field at the guide's nodes on one saved plane, in V/m.

instantaneous_flux(output, *, guide[, ...])

Return the instantaneous Poynting flux of one saved plane, in watts.

magnetic_field(output, *, guide[, tables, ...])

Return the magnetic field at the guide's nodes on one saved plane, in A/m.

physical_energy(output, *[, plane, z])

Return the physical energy through a plane, or through every plane, in joules.

plane_nodes(output, *, guide[, tables, plane, z])

Return where one saved plane is reconstructed: its nodes and area weights.

reconstructed_flux(output, *, guide[, ...])

Return the cycle-averaged Poynting flux of one saved plane, in watts.

reference_tables(output, *, guide)

Rebuild a general modal run's E/H reference tables from its guide.

solprop.processing.modal.channel_amplitudes(electric, magnetic, tables)[source]#

Recover channel amplitudes from a nodal E/H pair, in the square root of watts.

The inverse of the synthesis electric_field() and magnetic_field() perform, through the coefficient dual of ModalTransformTables: a_m = sum_q w_q [W^-1]_mn (E x conj(h_n) + conj(e_n) x H)_z / 4, the same Hermitian pairing the flux metric is built from. It is amplitude recovery and not source projection, which carries the separate -i omega factor.

Reprojecting a physical field that was not synthesised from this basis creates a new initial-value problem; it is not a resume path.

Parameters:
electricnumpy.ndarray

Nodal electric spectrum, shape (n_nodes, 3, n_omega), V/m, internal convention.

magneticnumpy.ndarray

Nodal magnetic spectrum, same shape, A/m.

tablessolprop.translate.modal_tables.ModalTransformTables

The reference the fields were synthesised from, carrying its coordinate_dual.

Returns:
numpy.ndarray

The amplitudes, shape (n_modes, n_omega), square root of watts.

Raises:
solprop.exceptions.OutputError

If the record carries no coefficient dual, or the fields do not match its node and frequency extents.

solprop.processing.modal.channel_labels(output)[source]#

Return the ordered channel labels a file records for its mode axis.

The run record persists one solprop.modes.protocol.ChannelLabel per row of the mode axis, so a plot legend, a selection by name and a resume check all read the same identity. A record whose mode records were built without labels names its channels by class and position only, and is refused.

Parameters:
outputsolprop.output.store.Output

An opened output handler.

Returns:
tuple

One label per mode-axis row, in state order.

Raises:
solprop.exceptions.OutputError

If the handler holds no record, or the record carries no labels.

Examples

>>> from solprop.processing._examples import example_general_output
>>> from solprop.processing.modal import channel_labels
>>> [label.display_label for label in channel_labels(example_general_output())]
['HE1,1:even']
solprop.processing.modal.coordinate_intensity(output, *, guide, tables=None, plane=None, z=None)[source]#

Return the flux density each channel would carry alone, in W/m^2.

The coordinate decomposition of the intensity: channel m’s own analytic flux density Re(E^m x conj(H^m))/2 . z, with E^m synthesised from that channel alone. It is what a per-mode intensity means on a modal basis.

It is not additive. The sum over channels of these densities is the physical flux density only where the channels do not interfere; in general the difference is the cross term, which is exactly what reconstructed_flux() with density carries and this does not. Even a positive spectral metric does not make an instantaneous cross-frequency flux a sum of coordinate powers. Nothing is clipped, here or there.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with. The reference is rebuilt from it when tables is not given, and its sampling and regions are checked against the file’s own guide identity, which the tables’ identity cannot see. Required.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The run’s reference tables, rebuilt from guide by default; pass them to reuse one rebuild across many calls. Their identity is checked against the file’s either way.

planeint or None, optional

Index of the plane wanted, negative from the end; the last by default.

zfloat or None, optional

Position of the plane instead, m: the nearest saved plane. Refused beside a plane.

Returns:
numpy.ndarray

The per-channel flux density, shape (n_modes, n_nodes, n_t), W/m^2.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, the tables or the guide are not the ones that produced the file, or the reference cannot be rebuilt from the guide.

solprop.exceptions.ProcessingError

If the plane is named both by index and by position.

solprop.processing.modal.electric_field(output, *, guide, tables=None, plane=None, z=None, analytic=False, convention='optics')[source]#

Return the electric field at the guide’s nodes on one saved plane, in V/m.

E_i(x_q, t) = sum_m e_i^m(x_q, omega) a_m(omega) transformed back to time, with e the stored reference in V/(m sqrt(W)) and a the saved amplitudes in the square root of watts. The three components are E_x, E_y, E_z. On a guide whose geometry moves along z, e and the nodes are the guide’s at the plane’s own position, solved again there (the module’s notes).

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with. The reference is rebuilt from it when tables is not given, and its sampling and regions are checked against the file’s own guide identity, which the tables’ identity cannot see. Required.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The run’s reference tables, rebuilt from guide by default; pass them to reuse one rebuild across many calls. Their identity is checked against the file’s either way.

planeint or None, optional

Index of the plane wanted, negative from the end; the last by default.

zfloat or None, optional

Position of the plane instead, m: the nearest saved plane. Refused beside a plane.

analyticbool, optional

Return the complex analytic signal instead of the real physical field. The real field is numpy.real of it, and the two flux accessors differ in exactly this choice.

convention{‘optics’, ‘fft’}, optional

Sign convention of the analytic signal, as every other accessor of solprop.processing takes it and with the same default: the optics convention of docs/dev/conventions.md section 2 unless 'fft' asks for the internal one the reference is solved in. The real field is convention-free, so this is read only with analytic.

Returns:
numpy.ndarray

The field, shape (n_nodes, 3, n_t), V/m; real unless analytic.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, the tables or the guide are not the ones that produced the file, or the reference cannot be rebuilt from the guide.

solprop.exceptions.ProcessingError

If the plane is named both by index and by position.

solprop.processing.modal.instantaneous_flux(output, *, guide, tables=None, plane=None, z=None, density=False)[source]#

Return the instantaneous Poynting flux of one saved plane, in watts.

(E x H) . z of the real fields, integrated over the cross-section. It carries the sum-frequency term the cycle-averaged reconstructed_flux() drops – the oscillation at twice the carrier – and averages to it over a cycle. Which one a measurement wants is a statement about the detector: an instrument slower than the carrier sees the analytic flux, and a field-resolved measurement sees this one.

The sum-frequency oscillation is aliased when the grid does not resolve it. The trace is formed from products of two real fields sampled on the run’s own time axis, so the term at 2 omega_0 is only representable while 2 omega_0 is below the grid’s Nyquist frequency. The sample values are exact either way – each is the product of two exact samples – and so is the integral identity below; what moves is the apparent frequency of the plotted oscillation, which folds to abs(2 omega_0 - 2 omega_Nyq). A field grid declared for a carrier near the top of its band will therefore show a slow ripple where the physical one is fast, and a plot that means to show the carrier beat needs a window sampled for it.

int inst dt equals int analytic dt when no sum-frequency content folds onto DC: the cross terms are an integer number of cycles in the window and integrate away only while none of them aliases to zero frequency. That holds whenever the spectrum’s support, doubled, stays clear of the sampling frequency’s multiples, which a run whose carrier is inside its declared band satisfies.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with. The reference is rebuilt from it when tables is not given, and its sampling and regions are checked against the file’s own guide identity, which the tables’ identity cannot see. Required.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The run’s reference tables, rebuilt from guide by default; pass them to reuse one rebuild across many calls. Their identity is checked against the file’s either way.

planeint or None, optional

Index of the plane wanted, negative from the end; the last by default.

zfloat or None, optional

Position of the plane instead, m: the nearest saved plane. Refused beside a plane.

densitybool, optional

Return the flux density at each node, (n_nodes, n_t) in W/m^2, instead of its weighted sum over the cross-section.

Returns:
numpy.ndarray

The flux, shape (n_t,) in W, or (n_nodes, n_t) in W/m^2 with density.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, the tables or the guide are not the ones that produced the file, or the reference cannot be rebuilt from the guide.

solprop.exceptions.ProcessingError

If the plane is named both by index and by position.

solprop.processing.modal.magnetic_field(output, *, guide, tables=None, plane=None, z=None, analytic=False, convention='optics')[source]#

Return the magnetic field at the guide’s nodes on one saved plane, in A/m.

The partner of electric_field(), from the stored magnetic reference in A/(m sqrt(W)). The pair is what makes a flux: the provider normalises every channel to unit longitudinal Poynting flux, so int Re(E x conj(H))/2 . z dA is one watt for a unit amplitude and the reconstruction carries SI units throughout.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with. The reference is rebuilt from it when tables is not given, and its sampling and regions are checked against the file’s own guide identity, which the tables’ identity cannot see. Required.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The run’s reference tables, rebuilt from guide by default; pass them to reuse one rebuild across many calls. Their identity is checked against the file’s either way.

planeint or None, optional

Index of the plane wanted, negative from the end; the last by default.

zfloat or None, optional

Position of the plane instead, m: the nearest saved plane. Refused beside a plane.

analyticbool, optional

Return the complex analytic signal instead of the real physical field.

convention{‘optics’, ‘fft’}, optional

Sign convention of the analytic signal, as electric_field() takes it and with the same default.

Returns:
numpy.ndarray

The field, shape (n_nodes, 3, n_t), A/m; real unless analytic.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, the tables or the guide are not the ones that produced the file, or the reference cannot be rebuilt from the guide.

solprop.exceptions.ProcessingError

If the plane is named both by index and by position.

solprop.processing.modal.physical_energy(output, *, plane=None, z=None)[source]#

Return the physical energy through a plane, or through every plane, in joules.

solprop.stats.physical_energy(), which is the same-frequency product of the state with the basis’s flux metric integrated over frequency, so a number read off a file and the number the run recorded agree to the bit. It is a scalar per plane because a coordinate energy is not additive on a basis that is not orthonormal. The run record holds the metric’s identity and not its arrays, so this accessor evaluates the unweighted form and refuses by name a record whose modal.metric.kind is not "identity" – the number it could form from the stored state alone is the answer for a different basis. Read the run’s own recorded physical_energy statistic, or reconstructed_flux() here, which reconstructs the physical flux from the guide’s stored reference and needs no metric at all.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

planeint or None, optional

Index of the plane wanted, negative from the end; with neither plane nor z, every plane is returned with a leading n_z axis.

zfloat or None, optional

Position of the plane wanted, m.

Returns:
numpy.ndarray

The energy, J, a scalar per plane.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one. If the recorded basis metric is not the identity, so that the weighted energy cannot be formed from the stored state.

Examples

>>> import numpy as np
>>> from solprop.processing._examples import example_general_output
>>> from solprop.processing.modal import physical_energy
>>> values = physical_energy(example_general_output())
>>> bool(np.allclose(values, values[0], rtol=1e-12))
True
solprop.processing.modal.plane_nodes(output, *, guide, tables=None, plane=None, z=None)[source]#

Return where one saved plane is reconstructed: its nodes and area weights.

The field accessors of this module return values at the guide’s quadrature nodes and integrate them with its area weights; this returns those nodes and weights, in the same order as the node axis of electric_field(), reconstructed_flux() with density=True and coordinate_intensity(). For a guide whose geometry does not move they are the tables’ own, the same at every plane. For a moving guide they are the plane’s own: the rule that has moved with the interfaces to that plane’s position, which is the provider’s rule asked for there exactly as the entrance rule was (solprop.modes.path.path_rule()) – the same rule the field accessors solve on, so no caller needs the translation layer to plot a plane.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with. The reference is rebuilt from it when tables is not given, and its sampling and regions are checked against the file’s own guide identity, which the tables’ identity cannot see. Required.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The run’s reference tables, rebuilt from guide by default; pass them to reuse one rebuild across many calls. Their identity is checked against the file’s either way.

planeint or None, optional

Index of the plane wanted, negative from the end; the last by default.

zfloat or None, optional

Position of the plane instead, m: the nearest saved plane. Refused beside a plane.

Returns:
tuple of numpy.ndarray

The node positions (x, y) in the cross-section, shape (n_nodes, 2) in m, and their area weights, shape (n_nodes,) in m^2, so that weights @ reconstructed_flux(..., density=True) is reconstructed_flux(...).

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, the tables or the guide are not the ones that produced the file, the reference cannot be rebuilt from the guide, or a moving guide cannot be solved again at the plane’s position.

solprop.exceptions.ProcessingError

If the plane is named both by index and by position.

Examples

>>> import numpy as np
>>> from solprop.processing._examples import example_general_run
>>> from solprop.processing.modal import plane_nodes, reconstructed_flux
>>> run, tables, guide = example_general_run()
>>> xy, weights = plane_nodes(run, guide=guide)
>>> xy.shape == (weights.size, 2)
True
>>> density = reconstructed_flux(run, guide=guide, tables=tables, density=True)
>>> flux = reconstructed_flux(run, guide=guide, tables=tables)
>>> bool(np.allclose(weights @ density, flux, rtol=1e-12, atol=0.0))
True
solprop.processing.modal.reconstructed_flux(output, *, guide, tables=None, plane=None, z=None, density=False)[source]#

Return the cycle-averaged Poynting flux of one saved plane, in watts.

Re(E_a x conj(H_a))/2 . z integrated over the cross-section with the guide’s own area weights, from the reconstructed analytic fields. This is the physical power through the plane at each instant, a trace in time, and it is not the trace the run statistic solprop.stats.analytic_flux() is the maximum of (hence the different name): that statistic is a scalar, the peak of the same-frequency diagonal, max_t sum_m |a_m(t)|^2, while this 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 as well. The two peaks differ by at most sum_ij |B_i||B_j||K_ij - 1|, measured at 1.3e-5 of the peak inside a bound of 3.4e-5 on the general-basis test fixture; their time integrals agree, because the cross-frequency terms are an integer number of cycles in the window. This one is the quantity a detector sees.

Negative values are kept. A broadband field’s Hermitian flux can go negative where two channels interfere; clipping it would make the trace look like a power and stop it integrating to the right energy.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with. The reference is rebuilt from it when tables is not given, and its sampling and regions are checked against the file’s own guide identity, which the tables’ identity cannot see. Required.

tablessolprop.translate.modal_tables.ModalTransformTables or None, optional

The run’s reference tables, rebuilt from guide by default; pass them to reuse one rebuild across many calls. Their identity is checked against the file’s either way.

planeint or None, optional

Index of the plane wanted, negative from the end; the last by default.

zfloat or None, optional

Position of the plane instead, m: the nearest saved plane. Refused beside a plane.

densitybool, optional

Return the flux density at each node, (n_nodes, n_t) in W/m^2, instead of its weighted sum over the cross-section.

Returns:
numpy.ndarray

The flux, shape (n_t,) in W, or (n_nodes, n_t) in W/m^2 with density.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, the tables or the guide are not the ones that produced the file, or the reference cannot be rebuilt from the guide.

solprop.exceptions.ProcessingError

If the plane is named both by index and by position.

solprop.processing.modal.reference_tables(output, *, guide)[source]#

Rebuild a general modal run’s E/H reference tables from its guide.

What every reconstruction accessor here does when it is not given tables=, done once: a loop over many planes passes the result to each call rather than rebuilding it each time. The tables are tabulated over the extent the file’s table identity records (solprop.translate.general.reference_tables()) and checked against that identity and the guide’s, path by path.

Parameters:
outputsolprop.output.store.Output

An opened output handler holding a general modal run.

guidesolprop.modes.guide.ModalGuide

The guide the run was made with.

Returns:
solprop.translate.modal_tables.ModalTransformTables

The run’s own reference tables.

Raises:
solprop.exceptions.OutputError

If the run is not a general modal one, its record carries no table extent, the reference cannot be rebuilt from the guide, or the guide is not the one that produced the file.

Examples

>>> from solprop.processing._examples import example_general_run
>>> from solprop.processing.modal import reconstructed_flux, reference_tables
>>> run, _, guide = example_general_run()
>>> tables = reference_tables(run, guide=guide)
>>> [
...     reconstructed_flux(run, guide=guide, tables=tables, plane=index).ndim
...     for index in (0, 1)
... ]
[1, 1]