Multimode (few-mode) coupled GNLSE¶

One input envelope per guided mode. All channels must share one :class:TemporalGrid (each wave's grid is the same object) and equal-length fields; each may carry its own central wavelength but the engine treats them all as co-polarized modal envelopes.

Shared scalar parameters (n2, alpha, A_eff, confinement_factor, length). One scalar γ is applied in every channel; mode-specific area/overlap corrections are to be handled at the caller by scaling fiber.A_eff.

Taylor coefficients [β₂, β₃, …] per mode (ps^k/m with Ω in rad/ps), or one shared array for every channel.

Unit of the dispersion coefficients. Default "ps^k/m".

Modal group delay β₁⁽ᵐ⁾ − β₁⁽⁰⁾ (SI, s/m) in the retarded frame of channel 0. None (default) = co-riding modes; forced group_delays[0] == 0.

Modal propagation-constant offset Δβ₀⁽ᵐ⁾ = β₀⁽ᵐ⁾ − β₀⁽⁰⁾ (rad/m) in the retarded frame of channel 0. Frequency-independent phase accumulated as e^{i Δβ₀ z} in each channel's linear step; this is the absolute modal phase the retarded-frame Taylor expansion omits, and it is what provides discrete intermodal quasi-phase matching (e.g. the GRIN geometric-parametric- instability ladder, where Δβ₀⁽ᵖ⁾ = −2πp/ξ from self-imaging).

Nonlinear coefficients:

• "lp_degenerate" (default) — degenerate-LP spatial-mode model: SPM 1, XPM 2/3, inter-modal FWM 2/3.
• "isotropic" — all-ones coefficients (Manakov-like spatially averaged modes; use for a non-degenerate basis).

Opt-in inter-modal four-wave mixing. Default False — the standard averaged few-mode model keeps only SPM/XPM (the heterodyne FWM beats wash out over the group-delay walk-off in real fiber).

OAM azimuthal order ℓ of each channel. When supplied (and FWM is on) FWM triples are restricted to ℓ_m = ℓ_n + ℓ_p − ℓ_q (transverse-photon-momentum balance for the A_n A_p A_q* term feeding channel m); otherwise every triplet is allowed.

This gate is the Poletti & Horak Eq. (18) type-2 spatial selection rule, not merely an approximation of it: their Q^(2) term in Eq. (6) is Q^(2)_plmn A_l* A_m A_n feeding channel p with l the conjugated field, so their balance m_m + m_n = m_p + m_l is the printed rule −m_p − m_l + m_m + m_n = 0; under the index map (p, l, m, n) = (m, q, n, p) it becomes ℓ_m + ℓ_q = ℓ_n + ℓ_p, which is this gate (verified element-wise in reproductions/poletti_2008_multimode).

Two caveats:

• The gate carries the spatial rule only. The polarisation rule Eq. (19) and the exact magnitudes are in the overlap tensor — pass them via fwm_weights / xpm_weights when a real fibre's mode functions are known.
• Uniform entries make the gate inert: if all labels are equal (e.g. [0, 0, 0], the common "these channels have no distinguished azimuthal order" case) the condition holds for every triplet and the gate is exactly the isotropic fallback of oam_l=None. It is a selection filter, not a cost control — it never reduces the engine's work, only the number of permitted exchanges.

Mode-specific SPM/XPM overlap weights (Mumtaz Eq. 8 style), an N×N real array. w[i, j] multiplies |A_j|² entering channel i (including i == j, i.e. the SPM slot). When given, this overrides the uniform coef_model factors.

Mode-specific FWM overlap weights, an N×N×N×N real array; w[m, n, p, q] weights the → m transition pumped by (n, p) consuming q. When given, it multiplies every allowed triple (OAM gating, if any, still applies first).

Include the Manley–Rowe-consistent back-conversion pump arm +2iγ f* A_m A_q A_n* in the FWM substep (requires include_fwm=True). With this on, Σ|A|² is conserved to RK4 round-off and strong pumps show the parametric back-conversion oscillation. Default False (pump-driven approximation: the pump evolves only through SPM/XPM).

Fixed step size (m); None uses length/num_steps.