solprop.coupling.remap#

Move a field plane onto another temporal lattice, or another reference.

regrid() is the one controlled temporal conversion of SEP 31 (section 4.5): each target bin receives the finite-time Fourier sum of the source’s analytic signal, zero outside its window, shifted by the change of reference (PlaneReference) so that the absolute spectrum is unchanged. It is a direct sum, evaluated only on target bins inside the source lattice’s span (beyond it the sum returns aliases), with the identical lattice in an unchanged reference copied inside the target’s band and zeroed outside it, as the sum leaves it. Light outside the target’s band or window is removed only on request (crop_band, truncate) and its share reported in a RegridReport; a record with light at its edges is not extended without truncate; nothing is renormalised. DEFAULT_TOLERANCE is the share of a record’s norm below which a band or window counts as unoccupied.

The map and the normalisation it preserves are in docs/guide/workflows/coupling.md, section “Moving a plane between grids”.

Module Attributes

DEFAULT_TOLERANCE

Share of a record's norm below which a band or a window is unoccupied.

Functions

regrid(plane, grid, *[, phase, delay, ...])

Convert a plane to another temporal lattice and reference.

Classes

RegridReport(method, source_lattice, ...)

What a temporal conversion did, and what it removed.

solprop.coupling.remap.DEFAULT_TOLERANCE = 1e-10#

Share of a record’s norm below which a band or a window is unoccupied.

Ten digits below the record: well above the rounding of a double-precision sum over a few thousand samples (about 1e-13 relative), and well below any share a person would call physical light. A share above it is occupied, and removing it is lossy.

class solprop.coupling.remap.RegridReport(method, source_lattice, target_lattice, shift, phase_shift, record_norm, window_loss, band_loss, edge_share, truncated, energy_in, energy_out)[source]#

Bases: object

What a temporal conversion did, and what it removed.

The shares are of the source’s record norm: the time-integrated squared analytic signal of every column, weighted by the column’s transverse weight (one for a modal basis, the Parseval weight times eps0 c / 2 for a spatial one), so that on an identity metric it is the energy in joules, and on a spatial one the vacuum-equivalent energy. The energies are physical.

Attributes:
method{‘copy’, ‘direct’}

Identity copy on an identical lattice and reference (the bins outside the target’s band zeroed), or the direct sum.

source_lattice, target_latticestr

lattice_identity() of the two grids.

shiftfloat

Record-time shift applied, old delay - new delay, s.

phase_shiftfloat

Phase applied, old phase - new phase, rad.

record_normfloat

The source’s record norm, in its units (above).

window_lossfloat

Share of the record norm outside the target window after the shift.

band_lossfloat

Share of the record norm outside the target’s active band.

edge_sharefloat

Share of the record norm inside the source’s temporal collar.

truncatedbool

Whether the record was declared zero outside its window or cropped to the target’s (truncate).

energy_infloat or None

Physical energy of the source, J; None when its metric is unknown.

energy_outfloat or None

Physical energy of the result, J; None when its metric is unknown.

band_loss: float#
edge_share: float#
energy_in: float | None#
energy_out: float | None#
method: Literal['copy', 'direct']#
phase_shift: float#
record_norm: float#
shift: float#
source_lattice: str#
target_lattice: str#
truncated: bool#
window_loss: float#
solprop.coupling.remap.regrid(plane, grid, *, phase=None, delay=None, truncate=False, crop_band=False, tolerance=1e-10, method='auto')[source]#

Convert a plane to another temporal lattice and reference.

The module’s notes give the map. The plane’s transverse representation, basis, geometry and medium are unchanged; only the temporal record moves.

Parameters:
planeFieldPlane

The source.

gridsolprop.grid.TimeGrid

The receiving temporal grid, field or envelope, of any length, spacing and carrier.

phasefloat or None, optional

The result’s reference phase, rad; None keeps the plane’s.

delayfloat or None, optional

The result’s reference delay (time origin), s; None keeps the plane’s. A later delay moves the record earlier in the window.

truncatebool, optional

Declare the record zero outside its window, so that a larger or shifted target may extend it, and allow the part outside the target window to be cut, with its share reported. Default False refuses both.

crop_bandbool, optional

Allow light outside the target’s active band to be removed, with its share reported. Default False refuses it.

tolerancefloat, optional

Share of the record norm below which a band or a window counts as unoccupied; default DEFAULT_TOLERANCE.

method{‘auto’, ‘direct’}, optional

'auto' copies on an identical lattice in an unchanged reference and evaluates the direct sum otherwise; 'direct' always evaluates it.

Returns:
tuple

The converted FieldPlane and its RegridReport.

Raises:
CouplingError

If the target band cannot hold the occupied frequencies, the target window the record, or a nonlocalised or unknown-exterior record would be extended, without the matching permission; or a value is invalid.

Examples

>>> import numpy as np
>>> from solprop.coupling import FieldPlane, PlaneBasis, PlaneGeometry, regrid
>>> from solprop.coupling import basis_identity
>>> from solprop.fourier import spectrum_to_optics
>>> from solprop.grid import EnvelopeGrid
>>> from solprop.pulses import GaussianPulse
>>> source = EnvelopeGrid.from_limits(1.0, 800e-9, (600e-9, 1.2e-6), 1e-12)
>>> target = EnvelopeGrid.from_limits(1.0, 800e-9, (500e-9, 1.5e-6), 2e-12)
>>> pulse = GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=1e-6)
>>> samples = spectrum_to_optics(pulse.build(source), kind="envelope")
>>> basis = PlaneBasis("modal", basis_identity("modal", {"modes": ["one"]}))
>>> plane = FieldPlane.from_samples(samples, source, PlaneGeometry(0.0),
...                                 exterior="zero", basis=basis)
>>> moved, report = regrid(plane, target)
>>> bool(np.isclose(moved.energy(), plane.energy(), rtol=1e-9))
True
>>> report.method, report.band_loss < 1e-10
('direct', True)