Add resonance flag diagnostics

[sergioald]

Summary

Fixes the resonance flag so it tracks the fundamental lateral mode, and adds explicit resonance diagnostics to run summaries.

Changed

• ldsfl/flowfield.py

  • changes _compute_flag(...) to use the sign of the fundamental mode, lamb2[0], instead of mode 6.

• ldsfl/flowfield_periodic.py

  • applies the same resonance-flag convention to the periodic flow path.

• ldsfl/resonance.py

  • adds helpers for the fundamental decay rate;
  • estimates the resonant aspect ratio beta_R;
  • returns a compact resonance report with state, flag, distance to resonance, decay rate, and influence length.

• ldsfl/main.py

  • includes the resonance report in each run summary.

• tests/test_resonance_diagnostics.py

  • checks that the free and periodic flags change sign across beta_R;
  • documents why mode 6 cannot be used as the resonance indicator;
  • checks that beta_R moves with grain size;
  • checks reported resonance states;
  • checks that the run summary includes resonance diagnostics.

Why

The existing _compute_flag(...) selected mode 6 when at least six modes were available. For realistic aspect ratios, Re(lambda2) for mode 6 remains strongly negative, so the flag was effectively always reported as sub-resonant.

The resonance transition is controlled by the fundamental lateral mode. Its decay rate changes sign at the resonant aspect ratio, separating sub-resonant and super-resonant regimes. Reporting this explicitly makes the solver output more interpretable and gives future validation work a stable diagnostic target.

Validation

python -m py_compile ldsfl/flowfield.py ldsfl/flowfield_periodic.py ldsfl/resonance.py ldsfl/main.py tests/test_resonance_diagnostics.py
python -m pytest tests/test_resonance_diagnostics.py
python -m pytest
python -m run_ldsfl --base-dir . --cases 1 --max-steps 100 --no-plots

Notes

This PR changes a diagnostic flag and adds a resonance report.

It does not change the morphodynamic update algorithm, curvature calculation, flow-field velocity solution, GUI interface, output naming, fixture structure, or generated output format.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 11a3e937a1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Cache inputs before bisecting resonance

For every run_case summary this line now bisects beta_R, which calls fundamental_decay_rate dozens of times; each of those calls recomputes the resistance parameters and runs _precompute_modes, including the expensive k0123 vertical integration. This adds seconds of post-processing even to very short CLI/GUI runs and scales across multi-case projects, although the bisection only needs the same fixed physical coefficients and the first lateral mode. Consider reusing the precomputed coefficients or a lighter single-mode/root function for the diagnostic.

Useful? React with 👍 / 👎.