AmpForm 0.9.0

Release 0.9.0

Yanked in favor of v0.9.1 due to #58.

Major refactoring and improvements to the dynamics module and documentation.

See all documentation for this version here.

💡 New features

Extracted function for coupled, or "mass-dependent", width (#45)

The running width / coupled width / mass dependent width used in relativisitc_breit_wigner_with_ff is useful to K-matrix and Flatté. It's now exposed as a separate function:

AmpForm now ships with a symplot mini-package (#47)

Previously, the mini-package symplot was only available to the documentation, or as a relative import to notebooks. This did not work well, especially for the notebooks and for Google Colab.

Added phase space factor functions and added visualizations (#51)

Adds the functions phase_space_factor and phase_space_factor_ac, with references. The functions are, however, not yet implemented into the dynamic lineshapes.

Implement analytic continuation (#52 and #56)

Implemented phase_space_factor that was introduced by #51 into the coupled_width. The 'default' phase_space_factor has been adapted so that it can handle negative square roots.

Note: the overall lineshape of amplitude models does not change in the domain where it was defined so far. Only undefined domains are extended (see test_dynamics.py).

⚠️ Interface

BlattWeisskopf now uses z as argument, not q and d (#40)

Let the BlattWeisskopf callable only depend on z and angular_momentum. This leaves leaves the responsibility of setting z equal to break-up momentum times meson radius to the caller (too much logics going on within this class + this z = d * q is just one way to define things).

Improved API of dynamics module (#41, #54, and d79583d)

• The main dynamics module now only contains lineshape functions (801c7d9). This allows for cleaner imports, like :

  from ampform.dynamics import relativistic_breit_wigner

• Decorators that facilitate subclassing sympy.Expr have been isolated under dynamics.decorator (c1422ff)
• dynamics.builder can remain as it is (no circular dependencies), but its docstrings have been improved (ba24b2a)
• doit(), def_assumptions, and evaluate() are now hidden from the API (1c79ce4)
• Sub-classes of UnevaluatedExpr do not convert the args into properties anymore (bb1675a). This was causing a lot of code cluttering and those properties are not that useful.
• breakup_momentum now has references to the PDG (in preparation of analytic continuation) (020c5b3)

Return square value of break-up momentum (#48)

The original breakup_momentum contains a sqrt. This is inconvenient for the caller, because it does not allow handling negative values the break-up momentum squared. This is becomes important in phase space factors.

Use Mandelstam 𝑠 instead of 𝑚² (#49)

Comparable to #48, this allows handling negative values of 𝑠 or 𝑚².

Switch to square value of Blatt-Weisskopf (#53)

The value of Blatt-Weisskopf squared can be negative. This leaves it up to the caller how to handle these negative values if a square root is to be taken. Note that this becomes particularly important when the Blatt-Weisskopf function is used as a damping factor, like in relativistic_breit_wigner_with_ff and create_non_dynamics_with_ff, as opposed to coupled_width (where the square value is used).

Also improved some of the references for the lineshapes. In addition, a new interactive widget shows the effect of a Blatt-Weisskopf factor.

📝 Documentation

Improved mathematical rendering in dynamics API (#43)

#42 makes it easier to dynamically generate latex for the math in behind the dynamics module. This makes it easier to cross-reference the formulas as follows:

Screenshot of generated API

It now also becomes easier to extract for instance running width (both in coding and in math definitions).

Annotations in API are now abbreviated (#44)

Make the API more readable by abbreviating type hints. This style also mimics what one sees in the codebase.

Old

New

Insert line breaks (optional)

There's also an experimental option autodoc_insert_signature_linebreaks to insert line breaks before each argument:

but this has been switched off because it doesn't look nicely everywhere.

Added interactive dynamics lineshape widgets (#50)

Show effect of Blatt-Weisskopf factor on break-up momentum (#53)

Also improved some of the references for the lineshapes. In addition, a new interactive widget shows the effect of a Blatt-Weisskopf factor.

Improve signature of coupled_width (#54)

The signature of functions that have arguments with functions as default values (for an argument that expects a callable) do not render well. So it's better to use Optional[PhaseSpaceFactor] = None instead.

Improve dynamics page with widget output (#55)

Added phase sliders in K-matrix animation (5eda627)

Removed brackets from parenthetical citations (dda5099)

These citations are already rendered as links, so there's no need to put brackets around them. E.g.

[Chung et al. 1995], pp.2—4

becomes

Chung et al. 1995, pp.2—4

🖱️ Developer Experience

Removed myst-nb glue cells (#42)

The lineshapes notebook was used to insert a mathematical rendering of the implementations in the dynamics module into its docstrings. This has some disadvantages:

• Output cells have to be updated whenever some implementation. This could be countered with pytest-notebook, but that is bothersome if a notebook generates figures.

• The link between the module and that notebook is note immediately clear.

The math is now inserted through Sphinx only (through conf.py), which makes it easier to extend the dynamics module with more lineshapes and render their mathematics.