Ampform

_See all documentation for this version [here](https://ampform.rtfd.io/en/0.13.0)._

💡 New features

<details>
<summary>Implemented spin alignment for mismatching decay topologies (6 and 245)</summary>

See problem description in [TR-015](https://compwa-org.readthedocs.io/report/015.html) and usage example [here](https://ampform--245.org.readthedocs.build/en/245/usage/helicity/spin-alignment.html). For an example with generated data, see [TR-013](https://compwa-org.readthedocs.io/report/013.html).

</details>


⚠️ Interface

<details>
<summary>Helicity angle notation is now more concise (208 and 209)</summary>

Compare [old notation](https://ampform.readthedocs.io/en/0.12.2/api/ampform.kinematics.html#ampform.kinematics.get_helicity_angle_label) and [new notation](https://ampform--209.org.readthedocs.build/en/209/api/ampform.kinematics.html#ampform.kinematics.get_helicity_angle_label).

</details>

<details>
<summary>Removed decay/naming functions from kinematics (227)</summary>

Cleaned up the `kinemetics` module by moving `determine_attached_final_state()` to `helicity.decay` and `get_helicity_angle_label()` to `helicity.naming`. Also extracted `get_boost_chain_suffix()` from `get_helicity_angle_label()` in preparation of 212.

</details>

<details>
<summary>Particle LaTeX names are now used in parameters names (228)</summary>

Parameter names that include particle (resonance) names now render more nicely as LaTeX. Compare [old](https://ampform--227.org.readthedocs.build/en/227/usage/amplitude.html#mathematical-formula) rendering with [new](https://ampform--228.org.readthedocs.build/en/228/usage/amplitude.html#mathematical-formula).

**WARNING**: You may have to modify your scripts if they get parameters by name from `HelicityModel.parameter_defaults`!

Other improvements:
- Particle LaTeX names in coefficient names are wrapped in curly braces so that they render correctly if there are also helicities as subscripts.
- Right sidebar (TOC) is unfolded unto the second level.
- `attrs` is rendered as an API link in code snippets as well.

</details>

_See all documentation for this version [here](https://ampform.rtfd.io/en/0.12.6)._

🐛 Bug fixes

<details>
<summary>AmpForm can only be installed with SymPy v1.8 or v1.9 (247)</summary>

See 248

</details>

_See all documentation for this version [here](https://ampform.rtfd.io/en/0.12.4)._

💡 New features

<details>
<summary>HelicityModel.parameter_defaults has been wrapped in a ParameterValues class (229 and 234)</summary>

228 has made some parameter names even longer and harder to get with `dict.__getitem__()`. This PR wraps the `parameter_defaults` in a [`ParameterValues`](https://ampform--229.org.readthedocs.build/en/229/api/ampform.helicity.html#ampform.helicity.ParameterValues) class that allows doing stuff like:

python
>>> import sympy as sp
>>> a, b, c = sp.symbols("a b c")
>>> from ampform.helicity import ParameterValues
>>> parameters = ParameterValues({a: 0.0, b: 1+1j, c: -2})
>>> parameters[a] get by sympy.Symbol

_See all documentation for this version [here](https://ampform.rtfd.io/en/0.12.3)._

💡 New features

<details>
<summary>Implemented scalar initial state mass switch (214)</summary>

Follow-up to 197. See usage [here](https://ampform--214.org.readthedocs.build/en/214/usage/amplitude.html#scalar-masses).

</details>

🔨 Internal maintenance

<details>
<summary>Simplified numpy.einsum in ArrayMultiplication numpification (218)</summary>

`ArrayMultiplication` lambdified to a recursive call to [`einsum()`](https://numpy.org/doc/stable/reference/generated/numpy.einsum.html), which results in larger lambdified code. This PR lambdifies the code to an einsum path, e.g. `...ij,...jk->...i`.

</details>

<details>
<summary>Upgraded to QRules v0.9.6 (219)</summary>

See release notes [QRules v0.9.6](https://github.com/ComPWA/qrules/releases/tag/0.9.6). Required for a consistent determination of opposite helicity states, see #212.

_Note that this can change helicity angle labels! See a324c9e_

</details>

📝 Documentation

<details>
<summary>Cleaned up kinematics module API (211)</summary>

Preview [here](https://ampform--211.org.readthedocs.build/en/211/api/ampform.kinematics.html). Compare to [v0.12.2](https://ampform.readthedocs.org/en/0.12.2/api/ampform.kinematics.html).

- Definitions in the API are follow the sorting of the source code.
- Hidden the classes for SymPy ArraySymbols by moving them to `ampform.sympy._array_expresssions`.
- Added docstrings to all remaining classes, like `BoostZ`.
- Improved the `docs/_extend_docstrings.py` script.
- Hidden several methods and attributes that come from `sympy.Basic`.
- See [commit history]() for other changes.

</details>

<details>
<summary>Documentation on RTD is now built on Python 3.8 (215)</summary>

[`sphinx-apidoc`](https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html) does not render the docstring for the `FourMomentumSymbol` type alias (#211) when running on Python 3.7. See for instance the [API preview of the latest PR](https://ampform--214.org.readthedocs.build/en/214/api/ampform.kinematics.html#ampform.kinematics.FourMomentumSymbol). The docstring is correctly rendered when building with Python 3.8, see preview [here](https://ampform--215.org.readthedocs.build/en/215/api/ampform.kinematics.html#ampform.kinematics.FourMomentumSymbol).

Note: RTD for QRules also switched to Python 3.8 in https://github.com/ComPWA/qrules/pull/136.

</details>

<details>
<summary>Code example are now automatically clickable with links to reference documentation (217 and 220)</summary>

- All code examples are now clickable with links to corresponding reference documentation (also external links APIs) with [`sphinx-codeautolink`](https://sphinx-codeautolink.readthedocs.io). Closes https://github.com/ComPWA/compwa-org/issues/106 [](https://ampform--217.org.readthedocs.build/en/217/usage/amplitude.html#scalar-masses)
- Updated to the first non-beta black release [22.1.0](https://github.com/psf/black/releases/tag/22.1.0). Most important style effect: [no space around power operator `**`](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-breaks-binary-operators).

</details>

🖱️ Developer Experience

<details>
<summary>Installed jupyterlab-myst for MyST editing in notebooks (217)</summary>

Installed [`jupyterlab-myst`](https://github.com/executablebooks/jupyterlab-myst)

</details>

_See all documentation for this version [here](https://ampform.rtfd.io/en/0.12.2)._

💡 New features

<details>
<summary>Implemented RelativisticBreitWignerBuilder (206)</summary>

Closes 205

This adds a new class, [`RelativisticBreitWignerBuilder`](https://ampform--206.org.readthedocs.build/en/206/api/ampform.dynamics.builder.html#ampform.dynamics.builder.RelativisticBreitWignerBuilder), which makes it possible to insert different kinds of [`PhaseSpaceFactorProtocol`](https://ampform.readthedocs.io/en/0.12.1/api/ampform.dynamics.html#ampform.dynamics.PhaseSpaceFactorProtocol)s into [`set_dynamics()`](https://ampform.readthedocs.io/en/0.12.x/api/ampform.helicity.html#ampform.helicity.HelicityAmplitudeBuilder.set_dynamics). See [here](https://ampform--206.org.readthedocs.build/en/206/usage/amplitude.html#set-dynamics) how to use.

Essentially, this class is an extension of builder functions such as [`create_relativistic_breit_wigner_with_ff()`](https://ampform.readthedocs.io/en/0.12.x/api/ampform.dynamics.builder.html#ampform.dynamics.builder.create_relativistic_breit_wigner_with_ff) that were used previously.

Note that this builder class will become more important in 151, which introduces yet another phase space factor.

</details>


📝 Documentation

<details>
<summary>Add Deepnote buttons on example noteboook pages (204)</summary>

Closes https://github.com/ComPWA/repo-maintenance/issues/43

[](https://ampform--204.org.readthedocs.build/en/204/usage/amplitude.html)


</details>

<details>
<summary>Type aliases in API are now abbreviated (207)</summary>

See https://github.com/ComPWA/compwa-org/issues/104

| Old | New |
| --- | --- |
| [](https://ampform.readthedocs.io/en/0.12.1/api/ampform.dynamics.builder.html#ampform.dynamics.builder.ResonanceDynamicsBuilder.__call__) | [](https://ampform--207.org.readthedocs.build/en/207/api/ampform.dynamics.builder.html#ampform.dynamics.builder.ResonanceDynamicsBuilder.__call__) |

Also addresses https://github.com/ComPWA/compwa-org/issues/103. Note, though, that `abbreviate_signature.py` (now `_relink_references.py`) is rather complex. This is in order to maintain compatibility with Sphinx <4.4, which is [installed in Python <3.8](https://github.com/ComPWA/ampform/blob/60b256dc5377ab7fe7b4c482062644ddb55f12ea/setup.cfg#L71).

</details>


🖱️ Developer Experience

<details>
<summary>Changed reqruiements upgrade cron job to bi-weekly (201)</summary>

</details>

_See all documentation for this version [here](https://ampform.rtfd.io/en/0.12.1)._

💡 New features

<details>
<summary>Implemented stable final state switch for inserting scalar mass values (197)</summary>

Usage example [here](https://ampform.readthedocs.io/en/0.12.1/usage/amplitude.html#stable-final-states).

</details>

<details>
<summary>Implemented HelicityAdapter.permutate_registered_topologies() (198)</summary>

Usage example [here](https://ampform.readthedocs.io/en/0.12.1/usage/amplitude.html#extend-kinematic-variables).

</details>

🐛 Bug fixes

<details>
<summary>Switched Re and Im labels in K-matrix demo (192)</summary>

</details>