feat: LPSE with SRS (and 1d support)

[physicistphil]

Summary

Adds stimulated Raman scattering (backward SRS) to the envelope-2d (lpse2d) solver. Until now the solver evolved the EPW potential against a prescribed pump with a TPD source only; the E1 scattered-light field existed in the state vector but was never advanced. This PR evolves E1 with a paraxial finite-difference solver and closes the loop by adding the SRS source to the EPW equation, so backscatter grows self-consistently from noise (or from an optional injected seed).

The physics is a direct translation of the raman.solver = 'fd' branch of lpse-matlab (m201805_matlabLpse_v11.m); line references to the MATLAB source are kept in the code comments so the two can be diffed by hand.

What's added

Raman light solver (adept/_lpse2d/core/raman.py, new)

Evolves the scattered-light envelope at w1 = w0 - wp0:

dE1/dt = i c²/(2 w1) ∇⊥² E1
       + i w1/2 (1 - wp0²/w1² · n/n_env) E1
       - i e/(4 w0 me) conj(∇²φ) E0
       + seed injection (optional)

with the cross-derivative terms of the 2D paraxial operator, and the same staggered explicit update as MATLAB's lightSplitStep (real part from the RHS at t, imaginary part from the RHS at t + dt/2).

SRS source in the EPW equation (core/epw.py)

srsSource = i e wp0/(4 me w0 w1) · (n/n_env) · E0·conj(E1), added to the potential each step. E1 is high-k filtered before the product (MATLAB's isSuppressHighKSource, cutoff 1.2 × k1_max) so only wavevectors near the light-wave envelope contribute; the pump is prescribed, so it is not filtered, matching the MATLAB static-laser path.

Sub-cycling and stability (helpers.py, datamodel.py)

The light update is conditionally stable (dt < ~dx² w1/c²), so it is sub-cycled inside each EPW step with the EPW potential held fixed. The number of sub-steps is derived from the stability bound generalized to 2D, or can be pinned with grid.light_substeps — a value that violates the bound raises rather than silently going unstable. Absorbing boundaries are applied every sub-step, since light crosses the absorber at ~c.

Optional Raman seed (drivers.E1)

A two-point antisymmetric injector at x = xmax - offset launches a -x-propagating wave at the local k1, with a configurable turn-on ramp and an optional 4th-order super-Gaussian transverse profile. The default offset (1.6 × boundary_width) keeps the injector clear of the absorber's tanh skirt, and a closer one warns. If the density at the injector is above the w1 critical density the seed is evanescent, so setup fails with a message pointing at the three ways out (lower density.max, move offset, or drop E1 and run noise-seeded).

Diagnostics

With SRS on, the default time series gains e1_sq and reflectivity — the latter is sqrt(eps1)·<|E1_y|²>_y / E0_source² at a probe on the low-density side, with the sqrt(eps1) factor accounting for the reduced group velocity relative to the vacuum pump. make_series_xarrays is now generic over whatever keys the save function returns instead of hard-coding e_sq/max_phi.

Quasi-1D (ny = 1) support

1D SRS is the cheap configuration to run and the one the MATLAB srs_1D case uses, but the field-save path assumed ≥2 transverse cells: interpax.interp2d returns NaN off a single y-node and RegularGridInterpolator rejects a single-node axis (filling 0). Both silently blanked every field artifact while the scalar series stayed valid. Added an x-only interpolation path for ny == 1 in the in-solve field saver and the background-density save, and adjusted the plotting to emit line plots vs kx instead of empty kx–ky maps.

Also in passing: density.basis: uniform now honors a val key instead of always returning 1.0, and the complex-dtype check in make_field_xarrays tests the actual float view rather than assuming complex128.

Config surface

terms:
  epw:
    source:
      srs: true          # new; default false, existing configs unaffected

grid:
  light_substeps: 8      # new, optional; derived from the stability limit if omitted

drivers:
  E1:                    # new, optional; without it SRS grows from the EPW noise source
    intensity: 1.0e+12W/cm^2
    delta_omega: 0.0     # fraction of w1
    turn_on_time: 10fs
    offset: 5um          # defaults to 1.6 * boundary_width
    yw: 20um             # omit for uniform in y

Example config: configs/envelope-2d/srs.yaml — noise-seeded backward SRS on a 0.18–0.28 n_c linear ramp, the srs_1D case.

Validation

tests/test_lpse2d/test_srs.py:

• test_srs_growth_rate (parametrized 2D and ny = 1) — noise-seeded homogeneous SRS. Fits the log-slope of the EPW energy over the late-time window and compares to the analytic backward-SRS rate gamma0 = k v_os/4 · wpe/sqrt(w_ek w_s), evaluated at the phase-matched k from a fixed-point solve of the Bohm–Gross/EM dispersion pair, with the pump wavenumber snapped to the FFT grid the way the solver launches it and the local density swelling folded into v_os. Agrees to 35%.
• test_srs_seed_propagation — pump and noise off, seed only. Checks the injected wave travels in -x, that its measured wavenumber matches the local k1 to 5%, and that its amplitude matches the injector calibration E1_source · sinc(k1 dx) / eps1^(1/4) to 30%.

Notes and limitations

• The pump is prescribed, so there is no pump depletion. E0 is reconstructed from the driver each step and is unaffected by E1, so reflectivities are only meaningful in the undepleted regime. Coupling depletion back into E0 is the natural follow-up.
• Cost. Sub-cycling means light_substeps extra RHS evaluations per EPW step, each with several FFT-free stencil passes plus one ifft2 of the potential Laplacian per step. On the shipped example config this is single-digit sub-steps; short dx at fixed dt raises it quadratically.
• The multi-color pump (drivers.E0.num_colors) composes with this for free — the Raman coupling consumes E0 as a field, so broadband SRS works without further changes, though it is not exercised by a test here.
• The 2D SRS path shares the noise-seeded growth test with the 1D one; there is no dedicated test of the transverse (cross-derivative) terms yet.

Known issue, pre-existing and not addressed here: drivers.E0.shape: arbitrary (the learnable amplitude/phase driver) looks broken on main. #168 broadcast the driver output to (num_colors, ny) and switched laser.Light.laser_update to index it as [i, :], but ArbitraryDriver.__call__ overrides UniformDriver.__call__ and still returns 1-D phases/intensities (modules/driver.py:174-178), so that path would raise on the first laser update. uniform/gaussian/lorentzian all inherit the broadcasting __call__ and are fine, and no shipped config or test exercises arbitrary, which is presumably why it has gone unnoticed. Flagging it rather than fixing it here to keep this PR to SRS — happy to fold in the one-line broadcast fix if reviewers would rather have it in the same change.

Base branch

Branched from main and independent of the osiris wrapper (#279) — the two lines of work touch a disjoint set of files, and this one is confined to adept/_lpse2d, configs/envelope-2d, docs/source/solvers/lpse2d, and tests/test_lpse2d.

🤖 Generated with Claude Code