[physicistphil]

Summary

Plan 2 of the lpse2d (envelope-2d) parity work with the original LPSE C++ (deck v5.1.2): everything that remained after #372 for 2-D physics except 3-D. Stacked on #372 (lpse2d/lpse-parity): the first 21 commits here are that PR; review the 15 commits from 1ebdb86's parent onward (git log lpse2d/lpse-parity..lpse2d/lpse-parity-plan2). Plan and results are in the research vault (Notes/adept/2026-09-16-103112-claude-lpse2d-parity-plan-2-*, 2026-09-17-140000-claude-lpse2d-plan2-tiers-l-o-*).

Prerequisites and numerics (P, N)

• Parity harness package (adept/_lpse2d/parity/: reference-run resolver, batch driver, run tags, job matrices), read_frames C-order fix, float64 enforced for parity runs.
• N.1: the test_010 growth deficit is the LPSE reference's own pump (a seam hot spot from its non-commensurate oblique injector); terms.light.snap_beam_ky reproduces either behaviour.
• N.3 noise_calibrate: lpse (LPSE's thermal-noise constant); N.5 reverse-mode gradient tests through every solver path.
• N.4: TPD + SRS on the separate-equation solver is refused as LPSE does (the shipped tpd-srs-iaw example moves to the combined formulation).

Three-component fields (F): E_z everywhere, beam/seed polarization angle (s-pol SRS), in-plane B and p_z in the 2-D HPE push, HPE energy-conservation multiplier ported from LPSE.

Light (L): FD stencil order 2/4/6 with the order-consistent TF/SF injector (terms.light.fd_order); PML absorbers (absorber: pml); resonance absorption (resonance_absorption); FD injection of oblique, multiple, profiled and leftward (x-max) beams; light spectrum probes (save.light_spectrum); initial_perturbation; source windows / injector suppression; terms.light.one_way diagnostic.

Kinetic (K): terms.qle — LPSE's quasilinear module (VDF diffusing in the EPW spectrum, Landau rates recomputed from ∇_v f), with three measured departures from the C++ documented in the module: an energy-balance-verified diffusion constant with the Bohm-Gross group-velocity Jacobian, a conservative flux form, and ∇f = f ∇ln f.

IAW (I): terms.iaw.solver: fd — LPSE's PPM finite-difference solver on a super-sampled grid with plasma-flow profiles (flow: linear / gaussian / log / file, temporal slope); CBET resonance localisation at the Mach ∓1 layers verified. Source windows and time gates (I.3).

Options (O): LPSE's absoluteThreshold search (threshold.find_threshold_lpse).

Translator fixes found on the way: laser.N.evolution.width (profiles were dropped; σ = W/√2), the fd-vs-spectral vote of an inactive Raman field, the spectral solver's incident-flux probe sitting inside its injector (spectral reflectivities logged before 1ebdb86 with the default probe offset are biased high; EPW growth ratios unaffected).

Status

Unit-tested (full tests/test_lpse2d: 252 passed, 56 min). Not yet compared with LPSE for the tier L / K / I decks (test_011, 012, 016, 019, 030, 029 > 1.5 ps, 001, 003): those reference runs need the blackbox binaries and are the next session. Draft until then.

🤖 Generated with Claude Code

[ergodic-reviewer]

Request changes for the attached P2 defect: FD-IAW noise bypasses the configured IAW wavenumber cap after the damping mask is applied, repopulating excluded modes that enter density feedback and saved results. The new coarse-to-fine band mapping is present; the remaining issue is the separate noise support.

Postprocessing: Implemented and separately callable through BaseLPSE2D.post_process; the numerical module call does not force plotting or artifact writing. Inspected code and implementation patches cover field/series analysis, persisted light-spectrum and QLE VDF/Landau datasets and plots, with artifact export through ergoExo. This finding affects the simulated data feeding those outputs, not an absence of postprocessing.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Oversized API responses prevented complete inspection of helpers.py, lpse_deck.py, and configuration documentation; smaller relevant commit patches were inspected where accessible. Complete diff coverage could not be verified.

[ergodic-reviewer]

[P2] Apply the retained IAW band to the FD noise kick too

In FDIonAcoustic.__init__, noise_band = (sqrt(fk_sq) < k_noise) & (fk_sq > 0) ignores the band constructed from iaw_low_pass_filter_grid. With terms.iaw.noise: true, positive Landau damping, and terms.iaw.max_wavenumber below the noise-disc radius, step.damp first removes excluded modes through damping_factor, then immediately repopulates them via noise_kick. Its final multiplication uses only noise_band, so the configured hard cap is bypassed on every noise update—even starting from zero fields on a periodic box. The next n -= dt * w transfers those modes into density, and IonAcousticWave._fd_step only FFT-truncates when returning the coarse density, allowing excluded coarse-grid modes into light/EPW feedback and saved IAW results.

Intersect the noise support with the mapped retained band (while retaining the additional noise-disc restriction). This follows the spectral IAW path, whose noise is constructed from self.filter, and the documented hard-cap contract. Add a regression combining noise with a restrictive IAW cap; the current noise test has no cap, while test_fd_kspace_band_is_the_coarse_mask_mode_by_mode checks only band/damping_factor, so neither exercises this bypass.

[physicistphil]

Fixed in 85f29cc. The FD noise support is now LPSE's noise disc intersected with the retained band (the mapped coarse mask, including terms.iaw.max_wavenumber), as the spectral solver's noise is built from its filter. The kick can no longer repopulate modes that the k-space damping removes.

Regression: test_iaw_fd.py::test_fd_noise_stays_inside_the_iaw_wavenumber_cap. With max_wavenumber: 1, so the cap lies inside the disc, one k-space step from rest leaves w_k zero above the cap (to 1e-9 of the largest) and nonzero below it. Before the fix, the largest kick sat above the cap. Merged into #387 (827531b). Docs: terms.iaw.noise row.

[ergodic-reviewer]

Request changes for the attached P2 defect: FD-combined propagation applies the small-step Landau approximation to every negative rate, understating inverse-Landau amplification outside that regime and disagreeing with exponential energy accounting.

Postprocessing: Implemented and separately callable through BaseLPSE2D.post_process; the numerical module call does not force plotting or artifact export. Inspected paths and implementation patches include field/series diagnostics, persisted light spectra and QLE VDF/Landau outputs, and plots, with artifact export through ergoExo. The finding affects the simulated fields and their damping/growth accounting, not an absence of postprocessing.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Oversized API responses prevented complete inspection of helpers.py, lpse_deck.py, and configuration documentation; smaller relevant commit patches were inspected where accessible. Complete diff coverage could not be verified.

[ergodic-reviewer]

[P2] Restrict the small-step approximation by magnitude for signed Landau rates

In FDCombinedSolver.langmuir_step, jnp.where(rate_dt < 1.0e-3, rate_dt, 1.0 - jnp.exp(-rate_dt)) selects the linear approximation for every negative rate, however large its magnitude. This is reachable through the new QLE Landau feedback and HPE allow_growth: __call__ passes their signed y["gamma_L"] straight into this method. Inverse-Landau modes therefore receive the first-order growth factor instead of the exponential outside the small-step regime, systematically understating their amplification. The neighboring CombinedSolver.propagate_combined uses exponential propagation, and both epw_dissipation and HPE expected_wave_loss use exponential energy accounting, so FD-combined growth can also disagree with its reported exchange. Test the approximation threshold against abs(rate_dt), or use -jnp.expm1(-rate_dt) directly, and cover a retained longitudinal mode with a negative rate outside the small-step regime.

[physicistphil]

Fixed in 85f29cc. FDCombinedSolver.langmuir_step now uses LPSE's linearised coefficient only for |γ dt| < 1e-3, and -expm1(-γ dt) otherwise. Small damping keeps LPSE's coefficient, so test_022 and similar decks are unchanged; a negative rate of any size outside that regime grows exponentially. LPSE tests the signed rate, so this departs from it for large negative rates.

Regression: test_fd_combined.py::test_langmuir_step_grows_negative_rates_exponentially, on a retained longitudinal mode at γ dt = −0.1, −5e-4, 5e-4 and 0.1, compared with exp or linear at rtol 1e-12. Before the fix the −0.1 case gave 1.1 instead of e^0.1 (0.47 % low). Merged into #387 (827531b).

[ergodic-reviewer]

Request changes for the attached P2 correctness defects:

• compare_hpe_flux averages LPSE flux over the whole reference run while fitting ADEPT wall energy only over the requested window, producing misleading parity ratios for transient fluxes.
• cmd_verify can print PASS and return zero when a previously finite stored diagnostic recomputes as NaN.

Postprocessing: Implemented and reachable, not absent. BaseLPSE2D separates the numerical call from post_process; ergoExo invokes analysis and exports artifacts. The parity harness returns datasets and can persist series.nc, fields.nc, and metrics.npy. The findings concern correctness of comparison and validation of those scientific outputs.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Oversized API responses prevented complete inspection of some large files/diffs, including helpers.py and lpse_deck.py; smaller accessible files and commit patches were inspected. Complete diff coverage could not be verified.

[ergodic-reviewer]

[P2] Apply the requested time window to the LPSE wall flux too

In compare_hpe_flux, _, flux = read_flux(flux_path) discards the reference timestamps and np.mean(flux[:, i, ...]) averages the entire run, while hpe_wall_power(series, cfg, window) fits ADEPT's cumulative wall energy only over lo < t <= hi. For a reference containing startup or later transient flux outside that window, the reported hpe_flux_ratio_* therefore compares different physical intervals. Even matching time-dependent wall powers can be reported as a parity discrepancy, and changing window only changes one side of the comparison. Retain the LPSE time array and restrict its flux samples to the same window (with an explicit empty-window check). Cover a reference whose flux differs inside and outside the selected interval; the existing flux test only checks parsing.

[physicistphil]

Fixed in 75d3399. compare_hpe_flux keeps LPSE's time column and averages only the samples with lo < t <= hi, in ps, the same interval hpe_wall_power fits. An empty window raises.

Regression (added in 7099c40, together with the verify test): test_parity_harness.py::test_hpe_flux_compares_the_same_time_window. A synthetic lpse.flux with flux 1 inside and 100 outside the window now gives exactly 1 (before the fix, 64), and an empty window is refused. Merged into #387 (2239faa).

[ergodic-reviewer]

[P2] Fail verification when a recomputed metric is non-finite

In cmd_verify, a NaN computed[k] makes err NaN, but worst = max(worst, err) leaves the finite running maximum unchanged. The loop prints MISMATCH, yet the final ok = worst <= args.rtol and not missing can still print PASS and return zero. This is reachable through harness.compare: for example, a NaN in the saved iaw_density_abs_max series makes the previously finite stored iaw_max_adept recompute as NaN without removing its key or any EPW/Raman ratios. Thus a damaged/non-finite diagnostic can pass the artifact-reproduction acceptance check. Explicitly reject non-finite stored/recomputed values (and accumulate failures independently of worst); add a test where a finite stored IAW maximum recomputes as NaN and require a nonzero exit status.

[physicistphil]

Fixed in 7099c40. The comparison is now _verify_report: a non-finite stored or recomputed value, or one outside rtol, counts as a failure per metric, alongside missing ones, so a NaN can no longer hide behind the finite running maximum.

Regression: test_parity_harness.py::test_verify_fails_when_a_recomputed_metric_is_non_finite. It drives cmd_verify with MLflow, the downloads and harness.compare stubbed. A finite stored iaw_max_adept that recomputes as NaN gives exit status 1, and matching metrics give 0. Before the fix: 0. Merged into #387 (2239faa).

[ergodic-reviewer]

Two previously reported correctness defects remain at this head; linking the existing inline threads rather than duplicating them:

• [P2] Compare HPE wall flux over the same time window. compare_hpe_flux still discards the LPSE timestamps and averages the entire reference run, while hpe_wall_power fits ADEPT's cumulative energy only over the requested interval. Startup or later transients therefore produce misleading parity ratios even when the wall powers agree within the selected window. Restrict the reference samples to the same interval and handle an empty window explicitly. Existing finding.
• [P2] Reject non-finite recomputed diagnostics in verification. In cmd_verify, a NaN error leaves worst = max(worst, err) unchanged, so the command can print a mismatch but still return PASS. A finite stored iaw_max_adept that recomputes as NaN is one reachable example. Explicitly reject non-finite values and track failures independently of the running maximum. Existing finding.

Postprocessing: Implemented and reachable: BaseLPSE2D separates simulation from its callable post_process; ergoExo invokes analysis and exports artifacts. The parity harness returns datasets and optionally saves series.nc, fields.nc, and metrics.npy. These findings affect scientific comparison and artifact validation, not the absence of an analysis path.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Tool output limits prevented complete inspection of the large helpers.py, lpse_deck.py, solver configuration documentation, and test_combined.py patches. Smaller relevant implementation patches were inspected where accessible; complete diff coverage could not be verified.

[ergodic-reviewer]

The latest documentation/docstring update does not address these previously reported correctness defects, both confirmed in the code at this head. Linking the existing inline findings rather than duplicating them:

• [P2] Use the same window for HPE flux comparisons. In parity/harness.py, compare_hpe_flux discards the reference timestamps and averages flux[:, i, ...] over the entire LPSE run, while hpe_wall_power fits ADEPT's cumulative wall energy only over the requested window. Transient wall flux therefore produces misleading parity ratios even when the selected intervals agree. Restrict the reference samples to the same interval and handle an empty window explicitly. Existing finding.
• [P2] Fail verification on non-finite recomputed diagnostics. In parity/__main__.py, a NaN relative error does not increase worst = max(worst, err), and ok checks only that maximum and missing keys. A previously finite iaw_max_adept recomputed as NaN can consequently print a mismatch yet return PASS and exit zero. Reject non-finite comparisons explicitly and track failure independently of the maximum. Existing finding.

Postprocessing: Implemented and separately callable through BaseLPSE2D.post_process, outside the numerical call; ergoExo invokes it and exports artifacts. Inspected implementation patches include light-spectrum datasets/plots and QLE VDF/Landau outputs. The parity harness returns datasets and optionally persists series.nc, fields.nc, and metrics.npy. These findings affect scientific comparison and validation, not the absence of usable outputs.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Tool output limits prevented complete diff coverage, including full inspection of helpers.py, lpse_deck.py, and the configuration reference. Individual files and smaller relevant commit patches were inspected; this is not a complete-diff sign-off.

[ergodic-reviewer]

The field-save merge and test updates leave these previously reported correctness defects in the current head. Linking the existing inline findings rather than duplicating them:

• [P2] Compare HPE flux over the same time window. parity/harness.py::compare_hpe_flux discards the LPSE timestamps and averages the entire reference run, while hpe_wall_power fits ADEPT's cumulative wall energy only over the requested interval. Startup or later transients therefore produce misleading parity ratios even when the selected intervals agree. Apply the same window to the reference samples and handle an empty window explicitly. Existing finding.
• [P2] Fail verification on non-finite recomputed diagnostics. In parity/__main__.py::cmd_verify, a NaN error does not increase worst = max(worst, err), and ok checks only that maximum and missing keys. A finite stored iaw_max_adept recomputed as NaN can print a mismatch yet return PASS and exit zero. Reject non-finite comparisons and track failure independently of the maximum. Existing finding.

Postprocessing: Implemented and separately callable through BaseLPSE2D.post_process, outside the numerical call; ergoExo invokes it and exports artifacts. The inspected field-save patch retains three-component light and QLE observations, including the coarse-grid Landau-rate mapping. The parity harness returns datasets and optionally persists series.nc, fields.nc, and metrics.npy. The findings affect scientific comparison and validation, not the absence of usable outputs.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Individual file diffs and smaller commit patches were inspected, but oversized responses left portions of large files inaccessible with these tools. Complete diff coverage could not be verified.

[ergodic-reviewer]

Request changes for the attached P2 defect: parity verify cannot read the full reference archives produced by run --full / log --full, preventing reproduction of their stored comparison metrics.

The HPE comparison-window and non-finite verification fixes are present, with corresponding regression tests inspected.

Postprocessing: Implemented and reachable through the separate BaseLPSE2D.post_process callable; the numerical call does not force plotting or artifact export. ergoExo invokes analysis and exports artifacts, and the parity harness returns datasets and optionally persists series.nc, fields.nc, and metrics.npy. This finding concerns a broken persisted-result verification path, not an absence of usable outputs.

Validation/scope: Static inspection only; no tests, simulations, benchmarks, or postprocessing were executed, and no external plots/artifacts were opened. Tool output limits prevented full inspection of large patches/files, including helpers.py, lpse_deck.py, the configuration reference, and test_combined.py. Individual file diffs and accessible smaller commit patches were inspected; this is not a complete-diff sign-off.

[ergodic-reviewer]

[P2] Resolve both reference layouts when verifying archived runs

For a normal LPSE run tree containing data/lpse.metrics, harness.log_reference(..., full=True) preserves that subdirectory under lpse_reference/. Thus parity run ... --full and parity log ... --full produce lpse_reference/data/lpse.metrics, not the flat path hard-coded in cmd_verify. The preceding download_run_artifacts(..., "lpse_reference/lpse.metrics") raises LookupError for such a fresh archive, and this comparison also assumes the flat layout. Users therefore cannot reproduce the stored metrics from the supported full-archive workflow. Resolve/download either metrics location and pass the resolved path to compare, using the existing reference.metrics_path / METRICS_LAYOUTS convention already used by run and log. Add a verify regression for a full archive as well as the flat archive.