Validation and Regression

Supported validation now centers on the maintained core, CLI, GUI, and plotting entry points. Historical comparison notebooks remain in the repository as reference material, but they are not the baseline for new workflows.

Automated Checks

Use the pytest suite as the primary regression gate:

  • pytest -m unit for deterministic helper and control-flow coverage.

  • pytest -m physics for numerical and stability checks.

  • pytest tests/test_cli_gui_parity.py when changes touch CLI/GUI parity.

  • pytest tests/test_plotting_tools.py tests/test_trajectory_plotter.py for maintained sweep and single-run plotting commands.

For broad local validation, run pytest from the repository root.

Maintained Plotting Validation

Sweep post-processing should use the packaged commands:

  • lw-generate-sweep-heatmap for publication-quality sweep heatmaps.

  • lw-plot-latest-live to follow the newest sweep log.

  • lw-plot-from-logcache-live for a specific sweep log in static or live mode.

  • lw-plot-trajectory for saved single-run JSON or NPZ trajectory files.

These tools are covered by focused CLI tests and should remain the supported surface for plotting-related changes.

For signed B2B energy-gain maps, the clearest reference style is:

lw-generate-sweep-heatmap results/sweeps/<sweep_dir> \
   --output gains.png --absolute-gains --log-param2 \
   --param1-min 1 --param1-max 140 --axis-param1-max 120 \
   --gain-min -50 --gain-max 50 --color-min -30 --color-max 40 \
   --num-contours 8 --no-markers --grey-zero --grey-centre 0 \
   --no-title

For bunch-to-bunch examples, interpret the maps as screening cases: the driver bunch proceeds through a virtual exit aperture shortly after the interaction point, which blocks direct line of sight to the rider downstream.

Reference Notebooks

examples/validation/core_vs_legacy_benchmark.ipynb and examples/validation/integrator_testbed.ipynb are kept as historical reference notebooks. They may be useful for understanding older analysis paths, but active development should prefer the maintained CLI, GUI, and pytest coverage described above.

When a validation run reveals a regression, preserve the config, command, and result artifact that reproduce it, then add a focused pytest case before fixing the implementation.