Skip to content

FIX: correct multichannel Breit–Wigner coupling - #199

Merged
redeboer merged 20 commits into
mainfrom
FIX/multichannel-breit-wigner
Aug 3, 2026
Merged

redeboer merged 20 commits into
mainfrom
FIX/multichannel-breit-wigner

Conversation

@redeboer

@redeboer redeboer commented Jul 16, 2026

Copy link
Copy Markdown
Member

Closes #198

✨ New features

  • New unfold_definitions() function in ampform_dpd.io that recursively collects one representative definition per expression class. Instances of the same class are grouped, arguments that are identical across the group are retained, differing atomic arguments (such as channel-indexed symbols) use the first instance, and differing composite arguments are replaced by a symbol named after the class parameter, so that h(1) renders as h(z). This replaces the hand-written {e: e.doit(deep=False) for e in exprs} lists in docs/serialization.ipynb.

⚠️ Interface changes

Old name New name
ChannelArguments.width ChannelArguments.coupling_squared

🐛 Bug fixes

  • ChannelArguments.evaluate() now returns $\Gamma_i(s) = \frac{g_i^2}{m_0} \rho_i(s) F_{L_i}^2(s)$ instead of $\Gamma_0 \frac{m_0}{\sqrt{s}} F_{L_i}^2(s)$. The gsq value of a channel in the serialized model is the coupling squared, not an energy width, so the phase space factor $\rho_i$ has to enter the running width explicitly.
  • SimpleBreitWigner.evaluate() uses exact sp.I instead of the Python float 1j, so the expression stays exact for symbolic and high-precision input.

❗ Behavioral changes

  • Any MultichannelBreitWigner built from existing gsq values now evaluates to a different lineshape. Couplings that were tuned against the old expression have to be re-fitted.
  • The gsq values of the $\Lambda(1405)$ channels in docs/Lc2ppiK.json are updated from 0.23395150538434703 to 0.328725260215546 to match the corrected convention.
  • docs/Lc2ppiK.json now uses point instead of name as the key in misc.amplitude_model_checksums, and gains per-propagator checksums plus the validation_point_m12sq, validation_point_m23sq, and validation_point_m31sq parameter points.

⚙️ Enhancements

  • MultichannelBreitWigner.evaluate() builds its running width with sp.Add(*self.channels) instead of summing channel.evaluate(), so the ChannelArguments nodes are kept unevaluated and can be unfolded separately.
  • LaTeX rendering of HelicityRecoupling, ParityRecoupling, and LSRecoupling uses \middle| instead of a bare |, so the separator scales with the surrounding brackets.
  • ChannelArguments renders as $\Gamma^\text{ch}(s; m_0, g^2)$, and MultichannelBreitWigner renders its channels by coupling squared.
  • formulate_multichannel_breit_wigner() uses keyword arguments and g_squared naming, making the coupling convention visible at the call site.

🖱️ Developer experience

  • New tests/test_dynamics.py with reference values imported from HadronicLineshapes.jl, covering:
    • agreement between a single-channel MultichannelBreitWigner and BreitWigner;
    • a two-channel S-wave against the Flatté reference value;
    • evaluation below threshold, including continuity across the branch cut when approached with an infinitesimal imaginary part.
  • New tests in tests/test_io.py for unfold_definitions(): recursive unfolding order, generalisation of composite arguments, preservation of channel-indexed symbols, and the no-op case.
  • .codex/ is added to .gitignore alongside the existing agent-configuration entries.

📝 Documentation

  • MultichannelBreitWigner and ChannelArguments now carry docstrings that spell out the lineshape formula and state explicitly that the channel argument is the coupling squared, with links to the amplitude-serialization convention, to HadronicLineshapes.jl, and to the related issues and pull requests.
  • The multi-channel Breit–Wigner section of docs/serialization.ipynb gained the same formula and a seealso box, and its plot is now rendered full-width.
  • New Validation section in docs/serialization.ipynb that compares every propagator against the reference values under misc.amplitude_model_checksums and marks the accuracy with 🟢, 🟡, and 🔴. The comparison is asserted with np.testing.assert_allclose(), so the notebook fails on a regression.
  • The form factor section now shows both the production and decay vertex of the $\Lambda(1520)$ chain, and links to the AmpForm documentation and TR-029.
  • A note on the Breit–Wigner-with-exponential section explains that the model file predates RUB-EP1/amplitude-serialization#69; see ComPWA/ampform-dpd#205.

Squash commit messages

* BREAK: rename `width` argument to `coupling_squared`
* DOC: document multichannel Breit-Wigner convention
* DOC: validate propagators against reference values
* DX: add agent configurations to `.gitignore`
* DX: import lineshape tests from HadronicLineshapes.jl
* ENH: render recoupling classes with `\middle`
* FEAT: implement `unfold_definitions()`
* FIX: use exact `sp.I` in `SimpleBreitWigner`

@redeboer redeboer added this to the 0.4.1 milestone Jul 16, 2026
@redeboer redeboer self-assigned this Jul 16, 2026
@redeboer redeboer added the 🐛 Bug Something isn't working label Jul 16, 2026
@redeboer
redeboer force-pushed the FIX/multichannel-breit-wigner branch from 2c24db0 to f450c64 Compare July 17, 2026 14:48
@redeboer redeboer added 📝 Docs Improvements or additions to documentation 🖱️ DX Improvements to the Developer Experience ❗ Behavior Changes that may affect the framework output labels Jul 31, 2026
@redeboer redeboer added ✨ Feature New feature added to the package ⚠️ Interface Breaking changes to the API ⚙️ Enhancement Improvements and optimizations of existing features labels Aug 3, 2026
@redeboer
redeboer marked this pull request as ready for review August 3, 2026 16:06
@redeboer
redeboer merged commit 4867968 into main Aug 3, 2026
21 checks passed
@redeboer
redeboer deleted the FIX/multichannel-breit-wigner branch August 3, 2026 16:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

❗ Behavior Changes that may affect the framework output 🐛 Bug Something isn't working 📝 Docs Improvements or additions to documentation 🖱️ DX Improvements to the Developer Experience ⚙️ Enhancement Improvements and optimizations of existing features ✨ Feature New feature added to the package ⚠️ Interface Breaking changes to the API

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Incorrect channel term in multichannel Breit–Wigner

2 participants