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 a per-frequency channel action to the canonical state. |
|
Refuse a step whose flow action exceeds the leaf's declared conditioning. |
|
Return the forward and inverse flow actions of one section over one length. |
|
Decompose the coupled flow this backend will execute, once. |
|
Return the explicit residual of one stage, |
|
Return the explicit residual's contribution to one stage's lab-frame source. |
Classes
|
|
|
What |
- class solprop.backends.numpy_ref.coupled_flow.BlockResidual(flow)[source]#
Bases:
objectR_s(z) statefor 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:
CoupledFlowFactorsWhat
numpy_refholds 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 ofG(z) - C(z)along z, flattened over(n_intervals, n_deg)in that order, so that the stage bundle’sflow_weightscombine them intoG(z_1) - C(z_1)exactly asphi_deltacombines the terms ofdPhi(docs/dev/kernel-contract.mdsection 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’sgrids.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.
- 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 onnorm(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 thedz_maxthe 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^HandU^-1 = Z exp(-l T) Z^H: the inverse is the matrix function of the negated exponent, never a numerical inverse ofU, 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.mdsection 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
Uon 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
Nonefor 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) uin the state’s layout, zero off the scored active bins.