solprop.backends.numpy_ref.passes.stepping#
The step arithmetic around a stage, and the once-per-step boundary treatments.
The interaction-picture Runge-Kutta trial’s own passes: stage_input() (pass 1:
combine the stages, return to the lab frame, add the noise), accumulate() (the
running solution and error), accept_step() (carry the step to its end) and
error_norm() (the controller’s scaled norm). stage_output() (pass 7:
normalise the polarisation and return to the step’s frame) serves every march: the
Adams, exponential and low-storage engines call it with a unit frame factor.
absorber_term() is the in-stage absorber beside it (ADR-025’s "nonlinear"
scheme); apply_hard_mask() and apply_temporal_rate() are applied once per
accepted step.
Functions
|
Return the in-stage absorbers as a contribution to the stage derivative. |
|
Advance the state over a completed step. |
|
Add one weighted stage derivative to a running accumulator. |
|
Zero the state outside the active band. |
|
Apply the temporal absorber as an exact rate over one accepted step. |
|
Reduce the embedded error estimate to the scaled norm the controller consumes. |
|
Combine the stages, return to the lab frame and add the noise. |
|
Normalise the polarisation and return it to the interaction picture. |
- solprop.backends.numpy_ref.passes.stepping.absorber_term(modal_t, temporal_rate_fine, radial, crop_index, active_mask, *, kind)[source]#
Return the in-stage absorbers as a contribution to the stage derivative.
The
"nonlinear"absorber scheme:-alpha(t) E(t) / 2on the modal time-domain field, transformed and cropped so that it can be added to the stage in the same place the normalised polarisation is.alphais a power coefficient, so the field carries the half (solprop.boundaries.nonlinear_absorber_term()). The radial route’s transverse collar is a matrix on the mode axis (solprop.backends.spatial.radial_absorber_matrix()) and adds to the same time-domain term, so both share one transform.It cannot ride the polarisation’s own transform, and this is the whole reason the two schemes exist: the polarisation is multiplied by the UPPE prefactor after the forward transform, and the absorber is already a rate on the field rather than a polarisation, so it would have to be divided by a prefactor that is exactly zero outside the active band. One extra modal forward transform per stage is its price, and it is what buys FSAL, since nothing then changes the state after the last stage of a step.
The fine grid is used rather than the coarse one because
alpha(t) E(t)has more bandwidth thanE(t)and the coarse grid would alias the product back into the band; the contract carries both axes for exactly this reason (kernel-contract.mdsection 5).The result is masked to the active band, as the polarisation beside it already is through a prefactor that is exactly zero there.
alpha(t) E(t)has content at every frequency, and the active mask is the statement that the equation is not solved outside that band: leaving it in would put content into the state that the accept pass’s hard mask then removes, which is both meaningless and enough to break the first-same-as-last identity (measured at 7.4e-7 before the mask and 1.8e-16 after it).- Parameters:
- modal_tnumpy.ndarray
The lab-frame modal field on the fine time grid, shape
(n_modes, n_pol, n_to), asto_time()produced it.- temporal_rate_finenumpy.ndarray or None
The collar rate on the fine time axis, 1/m, non-negative, shape
(n_to,);Nonewhen the temporal collar is not applied in-stage.- radialnumpy.ndarray or None
The radial collar’s matrix on the mode axis, 1/m, shape
(n_modes, n_modes);Noneoff the radial route or without its collar.- crop_indexnumpy.ndarray
Where each coarse bin sits in the fine spectrum,
numpy.intp, shape(n_omega,).- active_masknumpy.ndarray
The band the equation is solved on, Boolean, shape
(n_omega,).- kind{‘field’, ‘envelope’}
Spectral layout.
- Returns:
- numpy.ndarray
The absorber’s contribution on the coarse grid, complex128, shape
(n_modes, n_pol, n_omega), exactly zero outside the active band, in the same units as the stage derivative.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import absorber_term >>> field = np.ones((1, 1, 8)) >>> rate = np.full(8, 2.0) >>> index = np.arange(2, dtype=np.intp) >>> absorber_term(field, rate, None, index, np.ones(2, bool), kind="field").real array([[[-8., 0.]]])
- solprop.backends.numpy_ref.passes.stepping.accept_step(state, propagator, dz, accumulated)[source]#
Advance the state over a completed step.
y <- exp(dPhi) (y + h sum_i b_i k_i). The interaction picture is anchored at the start of the step, so the whole interaction-variable solution – the state and the accumulated stages together – is carried to the end of the step by one exponential. The same factor applied toh sum_i (b_i - bhat_i) k_igives the local error of the propagated state, which is whaterror_norm()scales.- Parameters:
- statenumpy.ndarray
The state at the anchor, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts.- propagatornumpy.ndarray
exp(dPhi)over the whole step, dimensionless, broadcastable against the state.- dzfloat
Length of the step, m, positive.
- accumulatednumpy.ndarray
sum_i b_i k_i, same shape as the state, in the square root of watts per metre.
- Returns:
- numpy.ndarray
The state at the end of the step, same shape and units.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import accept_step >>> state = np.ones((1, 1, 2), dtype=complex) >>> accept_step(state, 2.0 * np.ones_like(state), 0.5, state).ravel() array([3.+0.j, 3.+0.j])
- solprop.backends.numpy_ref.passes.stepping.accumulate(total, stage, weight)[source]#
Add one weighted stage derivative to a running accumulator.
total + w k_i. The solution and the embedded error are running accumulators rather than materialised stage combinations, so nothing beyond the stages the next one needs is kept.- Parameters:
- totalnumpy.ndarray
The accumulator so far, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts per metre.- stagenumpy.ndarray
The stage derivative
k_i, same shape and units.- weightfloat
The tableau weight:
b_ifor the solution,b_i - bhat_ifor the error.
- Returns:
- numpy.ndarray
The updated accumulator, same shape and units.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import accumulate >>> total = np.zeros((1, 1, 2), dtype=complex) >>> accumulate(total, np.ones_like(total), 0.5).ravel() array([0.5+0.j, 0.5+0.j])
- solprop.backends.numpy_ref.passes.stepping.apply_hard_mask(state, active_mask)[source]#
Zero the state outside the active band.
y <- y * active_mask, once per accepted step. The hard band limit is the one boundary that stays a 0/1 mask rather than becoming a rate, because it is idempotent: the operator and the prefactor are already exactly zero outside the active band, so nothing regrows there and the total absorption does not depend on the step count. The active mask, not the narrower in-band one, which would erase the spectral collar the rate acts on.- Parameters:
- statenumpy.ndarray
The state, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts.- active_masknumpy.ndarray
The active band,
omega_min/2 < omega < 1.1 omega_max, Boolean, shape(n_omega,).
- Returns:
- numpy.ndarray
The masked state, same shape and units.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import apply_hard_mask >>> state = np.ones((1, 1, 3), dtype=complex) >>> apply_hard_mask(state, np.array([True, True, False])).ravel() array([1.+0.j, 1.+0.j, 0.+0.j])
- solprop.backends.numpy_ref.passes.stepping.apply_temporal_rate(state, rate, dz, *, kind)[source]#
Apply the temporal absorber as an exact rate over one accepted step.
y <- F[F^-1[y] exp(-alpha(t) h / 2)], the split-step absorber scheme. The absorber cannot be folded intoPhibecause it is not diagonal in omega, and a per-step window would give total absorptionW^nand no converged answer; as a rate the factors telescope, so the total isexp(-alpha(t) L / 2)however the steps fall.alphais a power coefficient, hence the half on the field. On a field grid the real inverse transform drops the imaginary parts of the DC bin, and of the Nyquist bin of an evenn_t; the backends’ finishes mask both bins before the collar.- Parameters:
- statenumpy.ndarray
The state, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts. On a field grid its DC and Nyquist bins are real (above).- ratenumpy.ndarray
alpha(t)on the coarse time grid, float64, shape(n_t,), in 1/m, non-negative.- dzfloat
Length of the accepted step, m, positive.
- kind{‘field’, ‘envelope’}
Spectral layout.
- Returns:
- numpy.ndarray
The absorbed state, same shape and units.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import apply_temporal_rate >>> state = np.array([[[4.0 + 0.0j, 0.0j, 0.0j]]]) >>> absorbed = apply_temporal_rate(state, np.zeros(4), 1.0, kind="field") >>> bool(np.allclose(absorbed, state)) True
- solprop.backends.numpy_ref.passes.stepping.error_norm(error, state, state_new, norm_mask, controller)[source]#
Reduce the embedded error estimate to the scaled norm the controller consumes.
||e||_2 / (rtol max(||y||_2, ||y_new||_2) + atol)over the in-band mask, one global scale – the weak norm ofdocs/dev/stepper.mdsection 3. When the controller carries weights the scale is per bin instead and the division happens before the reduction; the magnitude stays global either way, because a per-element magnitude collapses the step to zero on a spectrum whose in-band dynamic range reaches 1e17 (section 10, trap 1).- Parameters:
- errornumpy.ndarray
The embedded difference of the propagated state, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts.- state, state_newnumpy.ndarray
The state before and after the trial step, same shape and units.
- norm_masknumpy.ndarray
The bins the norm scores (
grids.norm_mask, the controller’sregion), Boolean, shape(n_omega,).- controllersolprop.stepper.controller.PIController
The controller, which carries the tolerances and the choice of norm.
- Returns:
- float
The scaled norm, dimensionless. One means the step sat exactly at tolerance.
Examples
>>> import numpy as np >>> from solprop.stepper import PIController >>> from solprop.backends.numpy_ref.passes.stepping import error_norm >>> state = np.ones((1, 1, 2), dtype=complex) >>> mask = np.ones(2, dtype=bool) >>> control = PIController(rtol=1e-2, atol=0.0) >>> round(error_norm(1e-2 * state, state, state, mask, control), 12) 1.0
- solprop.backends.numpy_ref.passes.stepping.stage_input(state, stage_sum, dz, propagator, noise)[source]#
Combine the stages, return to the lab frame and add the noise.
u = exp(dPhi_i) (y + h sum_j a_ij k_j) + N(z_n + c_i h), the first pass ofarchitecture.mdsection 8. The interaction picture is anchored at the start of the step, soexp(dPhi_i)carries the stage input forward to where the nonlinear term is evaluated, and the shot-noise field is added there, in the frequency domain, where it costs one multiply-add and no transform.- Parameters:
- statenumpy.ndarray
The state at the anchor, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts.- stage_sumnumpy.ndarray
sum_j a_ij k_jin the interaction variable, same shape and dtype, in the square root of watts per metre.- dzfloat
Length of the step, m, positive.
- propagatornumpy.ndarray
exp(dPhi_i), dimensionless, broadcastable against the state.- noisenumpy.ndarray or None
The shot-noise field already advanced to this position,
N0 exp(i Im Phi(omega, z)), in the square root of watts, orNonewhen no noise model is active.
- Returns:
- numpy.ndarray
The lab-frame field the nonlinear term is evaluated at, same shape and dtype.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import stage_input >>> state = np.ones((1, 1, 2), dtype=complex) >>> zero = np.zeros_like(state) >>> stage_input(state, zero, 0.1, 2.0 * np.ones_like(state), None).ravel() array([2.+0.j, 2.+0.j])
- solprop.backends.numpy_ref.passes.stepping.stage_output(polarisation, prefactor, omega_window, inverse_propagator, absorber=None)[source]#
Normalise the polarisation and return it to the interaction picture.
k_i = exp(-dPhi_i) (p(omega, z) W(omega) crop(Ptilde) + A_i), pass 7 ofarchitecture.mdsection 8, withA_ithe temporal absorber’s own term when the"nonlinear"absorber scheme is active and nothing otherwise. The absorber sits beside the normalised polarisation rather than inside it because it is a rate on the field and not a polarisation: the prefactor does not apply to it. The prefactor is the UPPE factor-i omega / (2 eps0 c Re n_eff)(or its envelope form) with the crop scale folded in, and it is exactly zero outside the active band, so no unnormalised polarisation survives there for the stages and the error estimate to see.- Parameters:
- polarisationnumpy.ndarray
The modal polarisation on the coarse grid, complex128, shape
(n_modes, n_pol, n_omega), in C/m^2.- prefactornumpy.ndarray
responses.prefactor_at(responses, z), complex128, in the unitCompiledResponsesstates, broadcastable against the polarisation.- omega_windownumpy.ndarray
The spectral collar profile in
[0, 1], float64, shape(n_omega,).- inverse_propagatornumpy.ndarray
exp(-dPhi_i), dimensionless, broadcastable against the state; the negation of the exponentstage_input()used, never an independent evaluation.- absorbernumpy.ndarray or None, optional
The temporal absorber’s contribution from
absorber_term(), orNoneunder the"split_step"scheme, where the rate is applied to the state once per accepted step instead.
- Returns:
- numpy.ndarray
The stage derivative in the interaction variable, complex128, shape
(n_modes, n_pol, n_omega), in the square root of watts per metre.
Examples
>>> import numpy as np >>> from solprop.backends.numpy_ref.passes.stepping import stage_output >>> polarisation = np.ones((1, 1, 2), dtype=complex) >>> prefactor = np.array([[[-2.0j, 0.0j]]]) >>> unit = np.ones((1, 1, 2), dtype=complex) >>> stage_output(polarisation, prefactor, np.ones(2), unit).ravel().tolist() [-2j, 0j]