solprop.backends.numpy_ref.coupled_flow#

The coherent wall’s coupled linear flow, as the reference executes it (SEP 16).

A coupled_flow leaf mixes the channel axis per frequency bin. held_flow() decomposes it once into HeldFlow: each section’s Schur factors on the bins that carry a block, the residual’s terms and the declared conditioning certificate. flow_action() forms a step’s forward and inverse actions Z exp(+-l T) Z^H by scaling, a Taylor series and squaring; check_flow_conditioning() measures norm(U) norm(U^-1) and refuses a step above the certificate; apply_flow() mixes a state by an action. A "frozen_residual" flow adds an explicit residual to each stage’s source: residual_action() forms R_s(z), residual_drive() applies it on the scored bins, and BlockResidual keeps those actions for the Adams history’s samples.

Functions

apply_flow(state, action, active)

Apply a per-frequency channel action to the canonical state.

check_flow_conditioning(flow, section, pair, dz)

Refuse a step whose flow action exceeds the leaf's declared conditioning.

flow_action(flow, section, length)

Return the forward and inverse flow actions of one section over one length.

held_flow(problem)

Decompose the coupled flow this backend will execute, once.

residual_action(flow, section, weights)

Return the explicit residual of one stage, R_s(z_1), on the active bins.

residual_drive(lab, action, active, scored)

Return the explicit residual's contribution to one stage's lab-frame source.

Classes

BlockResidual(flow)

R_s(z) state for a held flow's positions (SEP 16 phases 5 and 6).

HeldFlow(active, vectors, triangular, ...)

What numpy_ref holds to execute one coherent block, frozen per section.

class solprop.backends.numpy_ref.coupled_flow.BlockResidual(flow)[source]#

Bases: object

R_s(z) state for a held flow’s positions (SEP 16 phases 5 and 6).

A history sample’s residual is formed against the section of every trial it serves, about six; its action depends only on the section and the sample’s flow weights, so each pair’s action is formed once and kept, the least recently used dropped first: each trial’s endpoint, at a new position, is used once.

Parameters:
flowHeldFlow

The held flow.

class solprop.backends.numpy_ref.coupled_flow.HeldFlow(active, vectors, triangular, frozen, condition_bound, residual_terms, residual_bins, n_modes)[source]#

Bases: CoupledFlowFactors

What numpy_ref holds to execute one coherent block, frozen per section.

The shared factors (CoupledFlowFactors, which native reads too), with the section axis leading and only the bins the generator is non-zero at held: the rest of the band has an identity action and the state is masked to zero there anyway.

A "constant_schur" leaf is the one-section case with no residual at all, and goes through exactly the constant-section arithmetic. A "frozen_residual" leaf adds residual_terms: the coefficients of G(z) - C(z) along z, flattened over (n_intervals, n_deg) in that order, so that the stage bundle’s flow_weights combine them into G(z_1) - C(z_1) exactly as phi_delta combines the terms of dPhi (docs/dev/kernel-contract.md section 1). The explicit residual is that combination minus the frozen block of the step’s own section. It is applied only on residual_bins, the active bins of the requested band; in the spectral collar outside them the frozen flow alone carries the state (docs/guide/waveguides/general-modal.md).

Attributes:
residual_binsnumpy.ndarray

Which bins the explicit residual is applied at, bool, shape (n_omega,): active and the problem’s grids.inband_mask, the requested band: in the collar beyond it the wall model is outside its validity, and the residual is left out whether or not the error norm scores there.

n_modesint

Channels the block couples.

n_modes: int#
residual_bins: Bool[ndarray, 'n_omega_scored']#
solprop.backends.numpy_ref.coupled_flow.apply_flow(state, action, active)[source]#

Apply a per-frequency channel action to the canonical state.

The identity case is the caller’s: a problem with no coupled flow, or the zero stage fraction, never reaches here.

Parameters:
statenumpy.ndarray

The state, or any array of its layout.

actionnumpy.ndarray

The action on the active bins, shape (n_active, n_modes, n_modes).

activenumpy.ndarray

Which bins carry the block, Boolean, shape (n_omega,).

Returns:
numpy.ndarray

The state with its channel axis mixed on the active bins and untouched off them, where the block is zero and the action is the identity.

solprop.backends.numpy_ref.coupled_flow.check_flow_conditioning(flow, section, pair, dz)[source]#

Refuse a step whose flow action exceeds the leaf’s declared conditioning.

The certificate row the translation layer declared is exp(dz_max (mu_max - mu_min)), a bound on norm(U)_2 norm(U^-1)_2; here the two spectral norms are measured, from the singular values of the actual action, and compared with it. That is the point of a certificate: the row is a claim the executor checks rather than a number it trusts, and a step longer than the dz_max the row was declared over is exactly what this catches.

The inverse is what the interaction picture carries the nonlinear source back by, so an unbounded one is an unbounded amplification of that source (the norm(g(b) - V^-1 N(V b)) inequality). Local re-anchoring is what keeps it bounded at all: the picture is re-anchored at every accepted step, so no inverse action is ever taken over more than one of them.

Parameters:
flowHeldFlow

The held flow, carrying the certificate.

sectionint

The step’s section.

pairtuple of numpy.ndarray

The forward and inverse actions over the whole step.

dzfloat

The length of the step, m, used in the refusal.

Raises:
BackendError

If the measured product exceeds the certificate by more than rounding.

solprop.backends.numpy_ref.coupled_flow.flow_action(flow, section, length)[source]#

Return the forward and inverse flow actions of one section over one length.

U = Z exp(l T) Z^H and U^-1 = Z exp(-l T) Z^H: the inverse is the matrix function of the negated exponent, never a numerical inverse of U, so the interaction picture’s backward action is as accurate as its forward one and does not inherit the conditioning of a solve (docs/dev/stepper.md section 4: no unbounded inverse propagation).

Parameters:
flowHeldFlow

The held flow.

sectionint

The section whose frozen block acts.

lengthfloat

The distance, m, positive for the forward action.

Returns:
forwardnumpy.ndarray

U on the active bins, shape (n_active, n_modes, n_modes).

inversenumpy.ndarray

U^-1, likewise.

solprop.backends.numpy_ref.coupled_flow.held_flow(problem)[source]#

Decompose the coupled flow this backend will execute, once.

Parameters:
problemsolprop.translate.problem.PropagationProblem

The validated problem.

Returns:
HeldFlow or None

The Schur factors and the certificate, or None for a problem carrying no coupled flow.

solprop.backends.numpy_ref.coupled_flow.residual_action(flow, section, weights)[source]#

Return the explicit residual of one stage, R_s(z_1), on the active bins.

R_s(z) = D(z) - D(z_s) + H(z) - H(z_s) - C(z), evaluated as one linear combination of the held terms over the bundle’s weights minus the frozen block of the step’s section. The weights are zero outside the section containing the stage’s own position, so no section’s expansion is extrapolated; the frozen block is the step’s, because the exponential the interaction picture is built on is, and freezing is a rearrangement of the same equation whichever block it names.

Parameters:
flowHeldFlow

The held flow, with its residual terms.

sectionint

The step’s section.

weightsnumpy.ndarray

The flow’s term weights at the stage’s position.

Returns:
numpy.ndarray

The residual in 1/m, shape (n_active, n_modes, n_modes).

solprop.backends.numpy_ref.coupled_flow.residual_drive(lab, action, active, scored)[source]#

Return the explicit residual’s contribution to one stage’s lab-frame source.

Unlike apply_flow(), which transforms a state and therefore leaves the bins it does not cover alone, this adds a term and is exactly zero off them: the residual is zero at every bin the wall formula was never evaluated at, and a copy of the state there would enter the source as a derivative of its own size.

It is also zero on the active bins the error norm does not score, the spectral collar. There the residual can reach a spectral radius the embedded pair is unstable at, at steps the in-band error allows, and nothing would see the growth; the frozen flow, exact at any step, carries those bins alone. The block is diagonal in frequency, so no in-band bin reads them through it; only the nonlinear source couples them in, at the size of the collar’s content.

Parameters:
labnumpy.ndarray

The stage’s lab-frame field u.

actionnumpy.ndarray

R_s(z_1) on the active bins, 1/m.

activenumpy.ndarray

Which bins carry the block, Boolean, shape (n_omega,).

scorednumpy.ndarray

The active bins the error norm scores, Boolean, shape (n_omega,).

Returns:
numpy.ndarray

R_s(z_1) u in the state’s layout, zero off the scored active bins.