solprop.backends.mlx_gpu.envelope

The envelope-grid plasma on the Metal device (SEP 33 section 6.3, phase 4).

The oracle (solprop.backends.numpy_ref.envelope_plasma) decomposes every sample’s two-component envelope by an SVD and refines its cycle moments with host decisions. On the device each sample is one thread of one custom kernel:

• the polarisation ellipse in closed form, native’s envelope_axes: the scaled Gram matrix’s eigenvalues by a scaled norm, the minor axis from the determinant, so that circular, nearly linear and degenerate (scalar) fields keep their limits;

• the cycle moments on the accepted rules of orders 64, 128, 256 and 512, split at the angles where the field crosses the table’s cutoffs – the panel past the low cut contributes nothing, the panel before the high cut the ceiling rate, and the field between them is held inside the table’s range, so that binary32’s rounding of a cut angle cannot put a node on the wrong side of a cutoff – each level’s sums compensated, and refined until two successive levels agree within the representation’s frozen budget (2e-6 relative, floor 1e-30 s^-1);

• the rate from the table’s spline as in rate_kernel() (an exact fma local coordinate, a double-float constant term);

• a failure flag per sample where the 512-point rule does not converge, which the backend reads with the step’s norm and turns into the oracle’s ConvergenceError.

Its discretisation (one refinement per sample, binary32 nodes and arithmetic) differs from the oracle’s binary64 adaptive evaluation, so it is qualified as a discretisation, class T, not as rounding.

Functions

envelope_cycle(field, cycle, exponent)

Return a channel's cycle-averaged rate, loss current per unit work and failures.

Classes

DeviceCycle(table, nodes, weights, ...)

A channel's cycle representation on the device.

class solprop.backends.mlx_gpu.envelope.DeviceCycle(table, nodes, weights, moment_rtol, negligible_rate)

Bases: object

A channel’s cycle representation on the device.

Attributes:

tableDeviceRateTable

The instantaneous rate table, narrowed.

nodesmlx.core.array

The four rules’ nodes on [-1, 1], (4, 512) float32, zero-padded.

weightsmlx.core.array

Their weights, likewise.

moment_rtolfloat

The refinement budget.

negligible_ratefloat

The comparison floor, s^-1.

moment_rtol: float

negligible_rate: float

nodes: mlx.core.array

table: DeviceRateTable

classmethod upload(cycle)

Narrow a validated cycle representation onto the device.

Parameters:

cyclesolprop.translate.envelope_plasma.CycleIntegralData

The channel’s rate table and rules.

Returns:

DeviceCycle

The device copy.

weights: mlx.core.array

solprop.backends.mlx_gpu.envelope.envelope_cycle(field, cycle, exponent)

Return a channel’s cycle-averaged rate, loss current per unit work and failures.

Parameters:

fieldmlx.core.array

The scaled envelope E, complex64, (n_nodes, n_pol, n_to); the physical field is 2**exponent E.

cycleDeviceCycle

The channel’s device representation.

exponentint

The state scale’s exponent.

Returns:

tuple of mlx.core.array

The rate, s^-1, (n_nodes, n_to); the loss current per unit ionisation work, complex64, of the field’s shape, for the physical field; and the number of samples whose refinement failed, int32, a scalar.