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.

A backend reduces its committed spectral state where the state lives and hands the edge an _EdgeReading, numbers and never the field. _HostEdgeReduction is the reference, on a host copy of the state, and everything else here is the same on every backend: the faces, the weights, the spacing, the ledgers and the judgement (SEP 44). 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 backstop starts at the guide's length over this many.
BACKSTOP_READS	The backstop grows to the guide's length over this many, no further (issue #396).
REACH_GROWTH	The relative growth of the reach that starts the backstop again.
NOISE_FACTOR	Standard deviations of one noise reading the allowance takes (section 5.3).

Classes

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

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

solprop.transverse_monitor.BACKSTOP_READS = 4

The backstop grows to the guide’s length over this many, no further (issue #396).

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.REACH_GROWTH = 0.1

The relative growth of the reach that starts the backstop again.

The reach moves by one transverse column between reads on a steady spectrum (5 % on the line case’s 1-D grid, whose kappa_q steps between neighbouring columns read to read); a tenth leaves that jitter alone.

solprop.transverse_monitor.READS = 16

The read spacing’s backstop starts at the guide’s length over this many.

class solprop.transverse_monitor.TransverseEdge(space, design, budget, stop_factor, length, band, k_min)

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)

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)

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

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

Returns:

bool

True with a requested collar.

finish()

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

k_min: float

launch(reading, z, *, noise, clean_columns=None, steps, reads, declared)

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

Parameters:

readingsolprop.transverse_monitor._EdgeReading

The launched state’s reading: every node, unless resumed.

zfloat

Its position, m.

noisenumpy.ndarray or None

The input noise it carries, if any, which is always a host array.

clean_columnsnumpy.ndarray or None, optional

Each column’s unweighted energy without that noise, for the safety ramp’s judgement. None when there is no noise, or the launch was resumed.

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

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

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

Returns:

float

A share of the launch energy, signed.

read(reading, z)

Take a reading at a committed position, credit the removals and judge.

Parameters:

readingsolprop.transverse_monitor._EdgeReading

The state’s reading.

zfloat

Its position, m.

Raises:

BoundaryError

When a face’s judged share exceeds stop_factor budgets.

reduction: _HostEdgeReduction

resume(record)

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.

property resumed: bool

Return whether this edge continues an earlier execution’s record.

Returns:

bool

True after resume() found a record, so that the launch is not judged.

space: RadialGrid | FreeGrid | PlanarGrid

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

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

Returns:

str

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

step(current, z)

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

Parameters:

currentfloat

The rectified current across the onset, unweighted by the launch.

zfloat

Its position, m.

stop_factor: float

summary()

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.

tables: _EdgeTables

wants_read(z)

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.