solprop.transverse_monitor#

The boundary monitor’s transverse edge (SEP 40 section 5.3).

A free-space run has a wall or a wrap at its grid’s outer size. With no real-space collar, whatever reaches the edge comes back, so reaching it is the failure: the monitor judges, per face, the energy in the outer 5 % of the outer size, its largest reading above its launch value, less a noise allowance, at the levels of solprop.monitor.BoundaryCheck. With a collar, reaching the edge is intended and what returns is the failure; the outward shares are recorded at INFO and the collar’s removal is credited.

Reads are spaced so that light cannot cross the edge unseen between two of them, min(L/16, 4 g / v_q) with g the guard’s width and v_q the reach of the current spectrum, and the spacing is a ceiling on the step. The safety ramp’s removal is credited per read interval and judged above the realised input noise’s own share. Every run reports a transverse_status; only clear is a clean verdict.

The field read is the backend’s committed spectral state; the reduction is the host’s, which numpy_ref carries in phase 1 of SEP 40. A backend that does not read the edge leaves the run unwatched, which it says before the first step.

Module Attributes

`GUARD`	The edge's width as a fraction of the outer size on its axis (SEP 40 section 5.3).
`READS`	The read spacing's ceiling is the guide's length over this many.
`NOISE_FACTOR`	Standard deviations of one noise reading the allowance takes (section 5.3).
`READ_RESOLUTION`	A read may leave out the frequencies whose energy together is at most this fraction of the warning (`budget**2` of the launch energy).

Classes

TransverseEdge(space, design, budget, ...)

The transverse edge of one free-space run: geometry, totals and record.

solprop.transverse_monitor.GUARD = 0.05#: The edge’s width as a fraction of the outer size on its axis (SEP 40 section 5.3).

solprop.transverse_monitor.NOISE_FACTOR = 8.0#: Standard deviations of one noise reading the allowance takes (section 5.3).

solprop.transverse_monitor.READS = 16#: The read spacing’s ceiling is the guide’s length over this many.

solprop.transverse_monitor.READ_RESOLUTION = 0.001#: A read may leave out the frequencies whose energy together is at most this fraction of the warning (budget**2 of the launch energy). By Parseval a frequency cannot put more on a face than it holds, so a face’s share reads low by at most that, a thousandth of what warns. A run’s light occupies a fraction of a grid’s frequencies at this level (from a fifth to a third on filaments and Kerr beams), and each read would otherwise synthesise them all (issue #453).

class solprop.transverse_monitor.TransverseEdge(space, design, budget, stop_factor, length, band, k_min)[source]#

Bases: object

The transverse edge of one free-space run: geometry, totals and record.

Attributes:

spacesolprop.grid.RadialGrid, solprop.grid.FreeGrid or PlanarGrid: The run’s grid.
designsolprop.spatial_absorber.SpatialAbsorberDesign or None: Its transverse boundary; None for spatial_absorber=False.
budgetfloat: The warning level as a field amplitude: energy shares above its square warn.
stop_factorfloat: Budgets above which a share stops the run.
lengthfloat: The guide’s length, m.
bandnumpy.ndarray: The requested band’s bins on the run’s frequency axis.
k_minfloat: The smallest wavenumber over the requested band, rad/m.

band: Int[ndarray, 'n_band']#

budget: float#

ceiling(z)[source]#

Return the longest step the reads allow from z: the read spacing.

A step is not made to land on a read. It is capped at the spacing, and the edge is read at the last committed position from which the next step would carry past the next read (due()), so reads stay at most a spacing apart without shortening the steps between them.

Parameters:

zfloat: The current position, m.

Returns:

float: The step, m; infinite when nothing is read.

design: SpatialAbsorberDesign | None#

due(z, proposal=0.0)[source]#

Return whether the edge is read at the committed position z.

Parameters:

zfloat: The committed position, m.
proposalfloat, optional: The next step proposed from z, m: the edge is read now when that step would carry past the next read.

Returns:

bool: True to call read().

property every_step: bool[source]#

Return whether the edge accumulates at every committed step (a collar).

Returns:

bool: True with a requested collar.

finish()[source]#

Log the edge’s verdict at the end of a run.

k_min: float#

launch(state, z, *, noise, steps, reads, declared)[source]#

Record the launch, judge it, and set the first read.

Parameters:

statenumpy.ndarray: The launched state, one member, spectral columns.
zfloat: Its position, m.
noisenumpy.ndarray or None: The input noise it carries, if any.
stepsnumpy.ndarray or None: A fixed schedule’s steps, which the read spacing cannot limit.
readsbool: Whether the backend reads the edge.
declaredbool: Whether the user declared content above discard_above.

Raises:

BoundaryError: When physical light launched into the safety ramp’s band exceeds ten budgets (section 5.3).

length: float#

property next_read: float[source]#

Return where the edge is next read, m; infinite when nothing is read.

A backend that marches without the host, as the native Adams march does, holds its steps to it as ceiling() does and hands the state back there.

Returns:

float: The position, m.

property ramp_removed: float[source]#

Return the safety ramp’s removal above noise and declared content.

Returns:

float: A share of the launch energy, signed.

read(state, z)[source]#

Read the edge at a committed position, credit the removals and judge.

Parameters:

statenumpy.ndarray: One member’s spectral columns.
zfloat: Its position, m.

Raises:

BoundaryError: When a face’s judged share exceeds stop_factor budgets.

resume(record)[source]#

Continue an earlier execution’s record of the edge (SEP 40 section 5.3).

The launch baselines and the totals are restored, so a resume judges against the original launch; launch() then records the resumed state unjudged.

Parameters:

recorddict: The transverse entry of the earlier monitor record.

space: RadialGrid | FreeGrid | PlanarGrid#

property status: Literal['clear', 'warned', 'stopped', 'insensitive', 'coarse', 'unwatched', 'off'][source]#

Return the run’s transverse status (section 5.3).

Returns:

str: clear, warned, stopped, insensitive, coarse or unwatched.

step(state, z)[source]#

Accumulate a collar’s inward current at a committed step (section 5.3).

Parameters:

statenumpy.ndarray: One member’s spectral columns.
zfloat: Its position, m.

stop_factor: float#

summary()[source]#

Return the edge’s record for the monitor’s.

Returns:

dict: JSON-ready values: the status and its reason, the faces, the launch energy and each face’s launch baseline, largest judged and raw shares, the noise allowance, the ramp’s removal (judged and raw) and a collar’s, the reads and the largest gap between them, and where it first warned.

wants_read(z)[source]#

Return whether a read at z would record anything.

A saved plane reads the edge whether or not the step that reached it already did, and a read at the position of the last one records nothing. Asking first spares the caller the state it would otherwise hand over for nothing, which on a device is a crossing of the whole state.

Parameters:

zfloat: The committed position, m.

Returns:

bool: False when nothing was launched, the edge is unwatched, or it was last read at z.