Ampform

See all documentation for this version [here](https://ampform.rtfd.io/en/0.11.3).

🐛 Bug fixes

<details>
<summary>import OrderedDict from collections instead of typing-extensions (162)</summary>

Previously, `OrderedDict` was imported from `typing-extensions`. This seems to work better for typing than `collections.OrderedDict`, but is only available in `typing-extensions==3.10.*`, see e.g.
https://github.com/ComPWA/tensorwaves/pull/327/checks?check_run_id=3717304158

Setting `typing-extensions>=3.10` as a lower limit however causes problems downstream for packages that use TensorFlow, see e.g. https://github.com/ComPWA/tensorwaves/pull/317

For now, it's therefore better to use collections.OrderedDict instead, so that there is no need to restrict typing-extensions.

</details>


📝 Documentation

<details>
<summary>Added Zenodo DOI badge (160)</summary>

Closes https://github.com/ComPWA/compwa-org/issues/55

[](https://doi.org/10.5281/zenodo.5526648)

</details>

_Release for first Zenodo DOI_
[](https://doi.org/10.5281/zenodo.5526648)

See all documentation for this version [here](https://ampform.rtfd.io/en/0.11.2).

💡 New features

<details>
<summary>Set CoupledWidth name through constructor (141)</summary>

`CoupledWidth._name` can now be set through the constructor, just like other classes that derive from `UnevaluatedExpression`.

</details>

<details>
<summary>Use multiple plot symbols in prepare_sliders (145)</summary>

Sometimes, you want to plot an expression with respect to several variables (like an _XY_-plot). This commit facilitates that.

</details>

<details>
<summary>Ordered components and parameter defaults in HelicityModel (146)</summary>

`HelicityModel.components` and `HelicityModel.parameter_defaults` are now ordered alphabetically, so that you can also get them by index. ([Not entirely straight-forward](https://stackoverflow.com/a/10058239/13219025), but at least now it's guaranteed that the items are orderd.)

</details>

<details>

<summary>Warning is emitted when resonance is not available in HelicityModel (148)</summary>

</details>

🐛 Bug fixes

<details>
<summary>Correctly set custom phsp_factor CoupledWidth (140)</summary>

`CoupledWidth` class did not set its `phsp_factor` attribute if it was specified in the constructor.

</details>

<details>
<summary>Determine phase space factor subscript from s (144)</summary>

Just like with `CoupledWidth`, the (optional) subscript in the latex rendering for this function should come from the decaying parameter (input argument `s`), not the decay products (input argument `m_a`).

</details>

<details>
<summary>Removed mdit-py-plugins version limit (147)</summary>

Dependency conflicts have been resolved by `myst-nb`.

</details>

📝 Documentation

<details>
<summary>Removed 0-below-threshold note for rel BW (143 and 371572e)</summary>

The docstring for `relativistic_breit_wigner_with_ff` still included a note about setting the damping factor to zero below threshold in case of zero angular momentum.

</details>

<details>
<summary>Embeded GPLv3+ license file (154)</summary>

Some platforms like Zenodo and conda-forge require the license file to be packaged.

</details>

<details>
<summary>Extended package description in README and removed tick-boxed (155)</summary>

Removed the tick-boxes, as they do not render correctly on PyPI

</details>

<details>
<summary>Added package description for PyPI (158)</summary>

Closes https://github.com/ComPWA/compwa-org/issues/61

</details>

🔨 Internal maintenance

<details>
<summary>Simplify doit implementation (142)</summary>

The `implement_doit_method` decorator would re-construct the class from its own arguments. It's better to directly call the `evaluate()` method though, because the class is already constructed once the method is called.

</details>

<details>
<summary>Removed mdit-py-plugins version limit (147)</summary>

Dependency conflicts have been resolved by `myst-nb`.

</details>

See all documentation for this version [here](https://ampform.rtfd.io/en/0.11.1).

🐛 Bug fixes

<details>
<summary>Classes deriving from UnevaluatedExpression are now pickled correctly (139)</summary>

A pickled `HelicityModel` could not be unpickled again, because the `UnevaluatedExpression._name` attribute was stored as a positional (i.e. required) argument in [`__getnewargs__`](https://docs.python.org/3/library/pickle.html#object.__getnewargs__).

</details>

Two major new changes:

- Added a **module for symbolic K-matrix and P-vector expressions**
- **Dynamics functions are now classes**, so that they can be more easily identified in the expression tree

See all documentation for this version [here](https://ampform.rtfd.io/en/0.11.0).

💡 New features

<details>
<summary>Added a module for symbolic, non-relativistic K-matrix computations for an arbitrary number of channels (117, 120, 121, 122, 127, 128, and 129)</summary>

Implemented [TR-005](https://compwa-org.rtfd.io/en/stable/report/005.html) and [TR-009](https://compwa-org.readthedocs.io/en/latest/report/009.html). Notable difference: this implementation provides **caching of the matrix multiplication** so that one can more easily switch between a different number of channels.

</details>

<details>
<summary>Implemented (non-)relativistic P-vector (123, 127, 131, and 132)</summary>

Implementation of [TR-010](https://compwa-org.readthedocs.io/en/stable/report/010.html).

Closes 118

</details>

<details>
<summary>Added symbol_to_arg and arg_to_symbol attribute to symplot.SliderKwargs (124)</summary>

Added a `symbol_to_arg` and `arg_to_symbol` property to `symplot.SliderKwargs`, as it is often needed in the visualization applets.

</details>

<details>
<summary>Maximum angular momentum in BlattWeisskopfSquared can now be limited (134)</summary>

Specifically for speeding up the widgets, see e.g. ad65784

</details>


⚠️ Interface

<details>
<summary>Dynamics functions are now wrapped in Expr classes (115, 119, and 138)</summary>

Inspired by https://github.com/ComPWA/compwa-org/pull/37 and https://github.com/ComPWA/compwa-org/pull/43, which required to re-define coupled width and other dynamics in terms of a class to make them render nicely, all expression nodes of dynamics functions are formulated in terms of `sympy.Expr` classes. This has been made possible with #114.

Note some major interface changes:
- `coupled_width` -> `CoupledWidth`
- `breakup_momentum_squared` -> `BreakupMomentumSquared`
- `phase_space_factor` -> `PhaseSpaceFactor`
(for this, the `PhaseSpaceFactor` had to be renamed to `PhaseSpaceFactorProtocol`)
- etc...

The `breakup_momentum` function has been removed.

Also added a (hidden) instance attribute `UnevaluatedExpr._name`, so that it can be used in the LaTeX rendering. In addition, the LaTeX rendering of of classes like `PhaseSpaceFactor` is affected by the name of their arguments (if they have any). This comes in handy in the relativistic K-matrix, when we want to distinguish between different `CoupledWidth`s and `PhaseSpaceFactor`s in the LaTeX rendering.

</details>

<details>
<summary>Renamed decorator sub-module to "sympy" (116)</summary>

The `ampform.dynamics.decorator` sub-module does more than just providing decorators. It generally contains functions that help building `sympy.Expr` classes (and instances), so it is better moved and renamed to a more general place: `ampform.sympy`.

</details>


📝 Documentation

<details>
<summary>Added comparison visualization of P-vector vs K-matrix (125)</summary>



</details>

<details>
<summary>Imported and improved K-matrix theory section from compwa-org (126 and 130)</summary>

Imported and bundled the theory sections from [TR-005](https://compwa-org.readthedocs.io/en/stable/report/005.html), [TR-009](https://compwa-org.readthedocs.io/en/stable/report/009.html), and [TR-010](https://compwa-org.readthedocs.io/en/stable/report/010.html). Many more notes were added and some problems have been pointed out as well. Sphinx preview [here](https://ampform--126.org.readthedocs.build/en/126/usage/dynamics/k-matrix.html).

</details>

<details>
<summary>Switched to compwa-org for the develop page (137)</summary>

</details>

See all documentation for this version [here](https://ampform.rtfd.io/en/0.10.5).

_Final release before [v0.11.0](https://github.com/ComPWA/ampform/milestone/16)._

🐛 Bug fixes

<details>
<summary>Implemented deep argument in doit instead of the new method (114)</summary>

Fixes a small bug that was introduced by the new function `create_expression`, which was introduced in 113. That function allowed handling the `deep` argument in `doit`, so that expressions containing a `BlattWeisskopfSquared` can be called with `doit(deep=False)`. The fix was faulty though; this PR is the correct implementation.

</details>

<details>
<summary>Slider descriptions now use HTML math mode (cafddea)</summary>

Math mode in ipywidgets doesn't render well when using LaTeX dollar signs for math mode. HTML math mode `\(...\)` works well both in Jupyter notebook and in HTML.

</details>

See all documentation for this version [here](https://ampform.rtfd.io/en/0.10.4).

💡 New features

<details>
<summary>Improved symplot.SliderKwargs class (109)</summary>

Some minor changes that improve usage of `symplot`, but don't affect interface. Required for https://github.com/ComPWA/compwa-org/pull/37.

- [x] Set step size (not number of steps) if `n_steps` is `float` in `set_ranges`
- [x] Un-hide `_sliders` and `_arg_to_symbol` attributes of `SliderKwargs`

</details>

<details>
<summary>Implemented symplot.substitute_indexed_symbols() function (111)</summary>

Implementation of [[TR-008] `Indexed` free symbols](https://compwa-org.readthedocs.io/en/stable/report/008.html)

</details>

<details>
<summary>Implemented symplot.partial_doit() function (112)</summary>

Helper function for https://github.com/ComPWA/compwa-org/pull/37

</details>


⚠️ Interface

<details>
<summary>Remove angular momentum projection from formulate_clebsch_gordan_coefficients (102)</summary>

See https://github.com/ComPWA/ampform/pull/100#issuecomment-886250406

</details>


🐛 Bug fixes

<details>
<summary>DOT is now wrapped in a figure (106)</summary>

Fixes 105

Bit of a clumsy solution, using the `figure` directive, but I don't see another way around it...

</details>

<details>
<summary>Remove verify_signature function (110)</summary>

This check makes the framework less flexible and the additional code is not worth the 'friendly' exception. It is required for https://github.com/ComPWA/compwa-org/pull/37, where a special class `PhaseSpaceFactor` is inserted into `coupled_width`.

</details>

<details>
<summary>UnevaluatedExpr can now be instantiated with a doit argument (113)</summary>

Previously, there something like `BlattWeisskopfSquared(...).doit(deep=False)` would crash. This fixes that behavior.

See also https://github.com/ComPWA/compwa-org/pull/37

</details>



📝 Documentation

<details>
<summary>Extended docstrings of helicity and kinematics modules (100)</summary>

Added several examples that explain the implementations in the `helicity` and `kinematics` modules.

A preview of the API can be viewed here:
https://ampform--100.org.readthedocs.build/en/100/api/ampform.html

</details>

<details>
<summary>Widen cell output where needed (103)</summary>

Widen cells where their input and/or output is so wide that a horizontal scrollbar appears. This can be done with the `full-width` tag:
https://sphinx-book-theme.readthedocs.io/en/latest/layout.html#full-width-content

For instance:


versus ([v0.10.3](https://ampform.readthedocs.io/en/0.10.3/usage/amplitude.html#build-sympy-expression)):

</details>


<details>
<summary>Documentation pages are wider now (104)</summary>

Ignored panel css to increase main content width. Otherwise the main content ends up being weirdly small. See:

- https://github.com/executablebooks/sphinx-book-theme/blob/547cc95674623345124d9bbea9e15e5b5fa34d0e/docs/conf.py#L62
- https://sphinx-panels.readthedocs.io/en/latest/index.html?highlight=panels_add_bootstrap_css#sphinx-configuration


Old:


New:

Many thanks to ianhi!


</details>


🖱️ Developer Experience

<details>
<summary>Switched to pre-commit.ci where possible (107)</summary>

See ComPWA/qrules87

</details>