Ampform

_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>

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

_Major interface changes: kinematic variables are not computed with NumPy anymore. Instead, AmpForm provides an expression for those conversions, so that the conversion can be done with different back-ends. See 177 for more info._

💡 New features

<details>
<summary>Kinematic variables are now expressed symbolically (177)</summary>

Closes 174

This PR implements [TR-011](https://compwa-org.readthedocs.io/en/stable/report/011.html). It merges the `ampform.data` module into `ampform.kinematics`. Most notably, the recursive helicity angles are now expressed as SymPy expressions, so that they can be computed with different computational back-ends.

</details>

<details>
<summary>AmpForm supports Python 3.10 (172)</summary>

</details>

⚠️ Interface

<details>
<summary>implement_doit_method decorator does not take arguments anymore (178)</summary>

The `implement_doit_method` decorator was using one inline function layer too many. So now you have to write

python
implement_doit_method
class MyExpr(UnevaluatedExpression):
...


instead of

python
implement_doit_method()
class MyExpr(UnevaluatedExpression):
...


</details>

<details>
<summary>Renamed CoupledWidth to EnergyDependentWidth (150)</summary>

The `CoupledWidth` class has been renamed to `EnergyDependentWidth`.

`CoupledWidth` was a bit confusing. More common terms are mass/energy dependent width or running width.

</details>

<details>
<summary>Added HelicityModel.kinematics, removed HelicityModel.adapter (177)</summary>

Several changes to `HelicityModel` due to 177. Most notably, its `adapter` attribute has been removed in favour of `kinematics`, which is a `dict` of helicity angle `Symbol`s to `Expr`s in terms of four-momentum symbols

</details>

🐛 Bug fixes

<details>
<summary>Minimum SymPy version set to v1.8 (185)</summary>

Google Colab comes with SymPy v1.7, which doesn't have the module `sympy.printing.numpy`. So at least SymPy v1.8 is required.

</details>

🔨 Internal maintenance

<details>
<summary>Importing ampform is about twice as fast now (189)</summary>

With https://github.com/ComPWA/qrules/pull/130 and f08f1f0, `import ampform` is about 2x as fast

</details>

<details>
<summary>_numpycode() printer methods now use SymPy's module_imports (187)</summary>

Classes like `ArrayAxisSum` were specifically using statements like

python
printer.module_imports["numpy"].add("sum")


This is problematic in TensorWaves, which would like to see `"jnp"` and `"tnp"` there (the NumPy interfaces of JAX and TensorFlow). This PR makes this possible.

Another major improvements: `einsum` in `ArrayMultiplication` is used in such a way that `transpose` is not necessary anymore. In addition, an ellipsis return statement is specificied (`"...ij,...j->...i"` instead of `"...ij,...j"`), which [`tf.einsum`](https://www.tensorflow.org/api_docs/python/tf/einsum) requires.

</details>

📝 Documentation

<details>
<summary>Links to Binder and Google Colab are now pinned for each version (179)</summary>

Branch name in `conf.py` is now extracted [from Read the Docs](https://docs.readthedocs.io/en/stable/builds.html) if possible. This way, all Binder/Colab links lead to the corresponding branch or tag of the repo.

</details>

🖱️ Developer Experience

<details>
<summary>Notebooks can now be run with pytest (186)</summary>

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

</details>

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

💡 New features

<details>
<summary>_numpycode() printer methods now use SymPy's module_imports (187)</summary>

Classes like `ArrayAxisSum` were specifically using statements like
python
printer.module_imports["numpy"].add("sum")

This is problematic in TensorWaves, which would like to see `"jnp"` and `"tnp"` there (the NumPy interfaces of JAX and TensorFlow). This PR makes this possible.

Another major improvements: `einsum` in `ArrayMultiplication` is used in such a way that `transpose` is not necessary anymore. In addition, an ellipsis return statement is specificied (`"...ij,...j->...i"` instead of `"...ij,...j"`), which [`tf.einsum`](https://www.tensorflow.org/api_docs/python/tf/einsum) requires.

</details>


🐛 Bug fixes

<details>
<summary>Minimum SymPy version set to v1.8 (185)</summary>

Google Colab comes with SymPy v1.7, which doesn't have the module `sympy.printing.numpy`. So at least SymPy v1.8 is required.

</details>


🖱️ Developer Experience

<details>
<summary>Notebooks can now be run with pytest (186)</summary>

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

</details>

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

💡 New features

<details>
<summary>Kinematic variables are now expressed symbolically (177)</summary>

Closes 174

This PR implements [TR-011](https://compwa-org.readthedocs.io/en/stable/report/011.html). It merges the `ampform.data` module into `ampform.kinematics`. Most notably, the recursive helicity angles are now expressed as SymPy expressions, so that they can be computed with different computational back-ends.

</details>

<details>
<summary>Python 3.10 is now supported (172)</summary>

</details>


⚠️ Interface

<details>
<summary>implement_doit_method decorator does not take arguments anymore (178)</summary>

The `implement_doit_method` decorator was using one inline function layer too many. So now you have to write

python
implement_doit_method
class MyExpr(UnevaluatedExpression):
...


instead of

python
implement_doit_method()
class MyExpr(UnevaluatedExpression):
...


</details>

<details>
<summary>Renamed CoupledWidth to EnergyDependentWidth (150)</summary>

The `CoupledWidth` class has been renamed to `EnergyDependentWidth`.

`CoupledWidth` was a bit confusing. More common terms are mass/energy dependent width or running width.

</details>

<details>
<summary>Added HelicityModel.kinematics, removed HelicityModel.adapter (177)</summary>

Several changes to `HelicityModel` due to 177. Most notably, its `adapter` attribute has been removed in favour of `kinematics`, which is a `dict` of helicity angle `Symbol`s to `Expr`s in terms of four-momentum symbols

</details>


📝 Documentation

<details>
<summary>Links to Binder and Google Colab are now pinned for each version (179)</summary>

Branch name in `conf.py` is now extracted [from Read the Docs](https://docs.readthedocs.io/en/stable/builds.html) if possible. This way, all Binder/Colab links lead to the corresponding branch or tag of the repo.

</details>

_Back-ported fixes that were introduced in the lead-up to [v0.12.0](https://github.com/ComPWA/ampform/releases/tag/0.12.0)_

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

🐛 Bug fixes

<details>
<summary>Allow installing any version of typing-extensions (191)</summary>

`TypeGuard` requires `typing-extensions` v3.10, which is not available to TensorFlow <2.7. With this PR, it is only required when doing style checks.

</details>

<details>
<summary>Minimum SymPy version set to v1.8 (185)</summary>

Google Colab comes with SymPy v1.7, which doesn't have the module `sympy.printing.numpy`. So at least SymPy v1.8 is required.

</details>

🔨 Internal maintenance

<details>
<summary>Importing ampform is about twice as fast now (189)</summary>

With https://github.com/ComPWA/qrules/pull/130 and f08f1f0, `import ampform` is about 2x as fast

</details>

<details>
<summary>Fixed ComplexSqrt __new__() method signature (187)</summary>

</details>

📝 Documentation

<details>
<summary>Links to Binder and Google Colab are now pinned for each version (179)</summary>

Branch name in `conf.py` is now extracted [from Read the Docs](https://docs.readthedocs.io/en/stable/builds.html) if possible. This way, all Binder/Colab links lead to the corresponding branch or tag of the repo.

</details>