**Yanked in favor of [v0.9.1](https://github.com/ComPWA/ampform/releases/tag/0.9.1) due to #58.**
_Major refactoring and improvements to the `dynamics` module and documentation._
See all documentation for this version [here](https://ampform.rtfd.io/en/0.9.0).
π‘ New features
<details>
<summary>Extracted function for coupled, or "mass-dependent", width (45)</summary>
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:
</details>
<details>
<summary>AmpForm now ships with a symplot mini-package (47)</summary>
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.
</details>
<details>
<summary>Added phase space factor functions and added visualizations (51)</summary>
Adds the functions phase_space_factor and phase_space_factor_ac, with references. The functions are, however, not yet implemented into the dynamic lineshapes.
</details>
<details>
<summary>Implement analytic continuation (52 and 56)</summary>
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`).
</details>
β οΈ Interface
<details>
<summary>BlattWeisskopf now uses z as argument, not q and d (40)</summary>
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).
</details>
<details>
<summary>Improved API of dynamics module (41, 54, and d79583d)</summary>
- The main `dynamics` module now only contains lineshape functions (801c7d9). This allows for cleaner imports, like :
python
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)
</details>
<details>
<summary>Return square value of break-up momentum (48)</summary>
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.
</details>
<details>
<summary>Use Mandelstam π instead of πΒ² (49)</summary>
Comparable to 48, this allows handling negative values of π or πΒ².
</details>
<details>
<summary>Switch to square value of Blatt-Weisskopf (53)</summary>
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.
</details>
π Documentation
<details>
<summary>Improved mathematical rendering in dynamics API (43)</summary>
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:
<details>
<summary>Screenshot of generated API</summary>
</details>
It now also becomes easier to extract for instance running width (both in coding and in math definitions).
</details>
<details>
<summary>Annotations in API are now abbreviated (44)</summary>
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.
</details>
<details>
<summary>Added interactive dynamics lineshape widgets (50)</summary>
</details>
<details>
<summary>Show effect of Blatt-Weisskopf factor on break-up momentum (53)</summary>
Also improved some of the references for the lineshapes. In addition, a new interactive widget shows the effect of a Blatt-Weisskopf factor.
</details>
<details>
<summary>Improve signature of coupled_width (54)</summary>
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.
</details>
<details>
<summary>Improve dynamics page with widget output (55)</summary>
</details>
<details>
<summary>Added phase sliders in K-matrix animation (5eda627)</summary>
</details>
<details>
<summary>Removed brackets from parenthetical citations (dda5099)</summary>
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
</details>
π±οΈ Developer Experience
<details>
<summary>Removed myst-nb glue cells (42)</summary>
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.
</details>