decayamplitude 0.1.0__tar.gz

decayamplitude-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+*.cpython*
+*.pyc
+*.coverage
+dist/
+*.xml
+*.png
+*.pdf
+node_modules/
+env/

decayamplitude-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+ci:
+  autoupdate_commit_msg: "MAINT: update pre-commit configuration"
+  autoupdate_schedule: quarterly
+
+repos:
+  - repo: meta
+    hooks:
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+
+  - repo: https://github.com/econchick/interrogate
+    rev: 1.7.0
+    hooks:
+      - id: interrogate
+        exclude: "src/decayangle/__*|tests/*|src/decayangle/backend.py"
+        args: [--fail-under=80, --verbose]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v1.16.0
+    hooks:
+      - id: codespell
+        name: codespell
+        description: Checks for common misspellings in text files.
+        entry: codespell README.md
+        language: python
+        types: [text]
+        exclude: "notebooks/*"
+
+  - repo: https://github.com/psf/black
+    rev: 24.4.2
+    hooks:
+      - id: black

decayamplitude-0.1.0/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Kai Habermann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decayamplitude-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: decayamplitude
+Version: 0.1.0
+Summary: A tool for modeling of amplitudes using jax
+Project-URL: Documentation, https://kaihabermann.github.io/decayamplitude/
+Project-URL: Issues, https://github.com/KaiHabermann/decayamplitude/issues
+Project-URL: Source, https://github.com/KaiHabermann/decayamplitude
+Author-email: Kai Habermann <kai.sebastian.habermann@cern.ch>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: decayangle==1.1.2
+Requires-Dist: jax
+Requires-Dist: jaxlib
+Requires-Dist: numpy
+Requires-Dist: sympy
+Description-Content-Type: text/markdown
+
+# Welcome to the decayamplitude software Project
+
+[![PyPI - Version](https://img.shields.io/pypi/v/decayamplitude.svg)](https://pypi.org/project/decayamplitude/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/decayamplitude.svg)](https://pypi.org/project/decayamplitude/)
+[![codecov](https://codecov.io/gh/KaiHabermann/decayamplitude/graph/badge.svg?token=KXBO8KEQ3V)](https://codecov.io/gh/KaiHabermann/decayamplitude)
+
+
+---
+
+**Table of Contents**
+
+- [Installation](#installation)
+- [Goal](#goal)
+- [Related projects](#related-projects)
+- [How to cite](#how-to-cite)
+- [License](#license)
+
+## Installation
+
+```console
+pip install decayamplitude
+```
+
+## Goal
+
+The software project `decayamplitude` provides an amplitude package working in tandem with `decayangle` to build full cascade reaction amplitudes. 
+The main goal is to provide a simple interface to build decay chains and their amplitudes, which can be used in amplitude analyses. 
+
+## Online Decay Editor
+
+There is a beta version of a web based decay editor, which is hosted [here](https://kaihabermann.github.io/DecaySelector/).
+The Website allows for an easy selection of a decay and resonances. Once finished a script generating an amplitude with `decayamplitude` can be downloaded.
+This is usually the easiest and quickest way to get a working amplitude. Explicit lineshapes need then to be defined by the user, where it is marked in the downloaded script.
+
+## Usage
+```python
+from decayamplitude.resonance import Resonance
+from decayamplitude.rotation import QN, Angular
+from decayamplitude.chain import DecayChain, MultiChain
+from decayamplitude.combiner import ChainCombiner
+
+
+
+
+from decayangle.decay_topology import Topology, Node, TopologyCollection
+
+# First we define the final state
+final_state_qn = {
+        1: QN(1, 1),
+        2: QN(2, 1),
+        3: QN(0, 1)
+    }
+
+# decayangles Topology class is used to generate the angular variables. Be carefull here, as fit results may depend on the ordering. 
+
+topology1 = Topology(
+    0,
+    decay_topology=((2,3), 1)
+)
+topology2 = Topology(
+    0,
+    decay_topology=((1, 2), 3)
+)
+
+# alternatively we can use the topology collection to define all topologies automatically
+tg = TopologyCollection(
+    0,
+    [1,2,3]
+)
+tg.topologies
+```
+
+We now have a basic definition of our decay scheme. But we need resonances to react. In general for a multi body decay we want to define a list of resonances for each isobar. Then let the code figure out all the possible decay chains.
+
+```python
+resonances1 = {
+    # we need to define resonances for each internal node of the decay chain
+    # A resonance needs a node, to which it couples, quantum numbers, a lineshape
+    # and a list of argument names, which will be used to map the parameters of the resonance 
+    # to the outside, once all our configurations are combined into an amplitude
+    (2,3): Resonance(topology1.nodes[(2, 3)], 
+                    quantum_numbers=QN(0, -1), 
+                    lineshape=BW_lineshape(topology1.nodes[(2, 3)].mass(momenta)), 
+                    argnames=["gamma1", "m01"]),
+
+    # since we can not only model decays, but also transitions from 2 particle
+        # to many particles
+    # Thus we may have to model multiple initial resonances and their production
+        # with a lineshape
+    # For decays we can use a constant lineshape 
+    # The preserve_parity flag controlls which L S couplings will be produced, 
+        # if one uses the automated generation of the possible couplings
+    # This has no effect if one plugs in couplings by hand
+    0: Resonance(Node(0), quantum_numbers=QN(1, 1),
+    lineshape=constant_lineshape, 
+    argnames=[], 
+    preserve_partity=False)
+
+# we use the argnames, to use the same mass for both BW lineshapes, but different widths
+resonances2 = {
+    (1, 2): Resonance(nodes_2[(1, 2)], quantum_numbers=QN(3, -1), lineshape=BW_lineshape(nodes_2[(1, 2)].mass(momenta)), argnames=["gamma2", "m01"]),
+    0: Resonance(Node(0), quantum_numbers=QN(1, 1), lineshape=constant_lineshape, argnames=[], preserve_partity=False)
+    }
+}
+```
+
+Now we can take the resonance dictionaries and combine them with a topology in order to produce a `DecayChain`. 
+
+```python
+chain1 = DecayChain(topology = topology1,
+        resonances = resonances1,
+        momenta = momenta,
+        final_state_qn = final_state_qn)
+
+chain2 = DecayChain(topology = topology2,
+        resonances = resonances2,
+        momenta = momenta,
+        final_state_qn = final_state_qn)
+```
+These chains are already able to produce a chain function, which can be evaluated for a given set of parameters. 
+
+```python
+chain1.chain_function
+```
+
+We can now combine the chains into a `ChainCombiner` object. This object will internally take care of the alignmeht operations.
+
+```python
+combined = ChainCombiner([chain1, chain2])
+
+# we can generate the unpolarized amplitude
+unpolarized, argnames = combined.unpolarized_amplitude(combined.generate_couplings())
+# unpolarized(*args) will return the amplitude for the given parameters
+
+# we can generate the matix elements depending on the polarization of the particles
+polarized, lambdas, argnames = combined.polarized_amplitude(combined.generate_couplings())
+# polarized(*lambdas, *args) will return the amplitude for the given parameters and polarization
+
+# here we get a list of aditional function parameters, which represent the polarization of the initial and final state particles
+# lambdas = ["h_0", "h_1", "h_2", "h_3"]
+
+# alternatively we can produce all matrix elements at once
+matrx_function, matrix_argnames = combined.matrix_function(combined.generate_couplings())
+# here we only have the initial state polarization as an additional parameter
+# matrix_argnames = ["h_0"] + argnames
+# matrx_function(h_0, *args) will return the amplitude for the given parameters and polarization
+
+```
+
+## Related projects
+
+Amplitude analyses dealing with non-zero spin of final-state particles have to implement wigner rotations in some way.
+However, there are a few projects addressing these rotations explicitly using analytic expressions in [DPD paper](https://inspirehep.net/literature/1758460), derived for three-body decays:
+
+- [ThreeBodyDecays.jl](https://github.com/mmikhasenko/ThreeBodyDecays.jl),
+- [SymbolicThreeBodyDecays.jl](https://github.com/mmikhasenko/SymbolicThreeBodyDecays.jl),
+- [ComPWA/ampform-dpd](https://github.com/ComPWA/ampform-dpd).
+
+## How to cite
+
+This software package as well as the closely related [decayangle](https://github.com/KaiHabermann/decayangle) should be cited by the accompaning paper
+[Wigner Rotations for Cascade Reactions](https://doi.org/10.1103/PhysRevD.111.056015)
+
+## License
+
+`decayamplitude` is distributed under the terms of the [MIT](https://mit-license.org/) license.

decayamplitude-0.1.0/README.md

@@ -0,0 +1,166 @@
+# Welcome to the decayamplitude software Project
+
+[![PyPI - Version](https://img.shields.io/pypi/v/decayamplitude.svg)](https://pypi.org/project/decayamplitude/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/decayamplitude.svg)](https://pypi.org/project/decayamplitude/)
+[![codecov](https://codecov.io/gh/KaiHabermann/decayamplitude/graph/badge.svg?token=KXBO8KEQ3V)](https://codecov.io/gh/KaiHabermann/decayamplitude)
+
+
+---
+
+**Table of Contents**
+
+- [Installation](#installation)
+- [Goal](#goal)
+- [Related projects](#related-projects)
+- [How to cite](#how-to-cite)
+- [License](#license)
+
+## Installation
+
+```console
+pip install decayamplitude
+```
+
+## Goal
+
+The software project `decayamplitude` provides an amplitude package working in tandem with `decayangle` to build full cascade reaction amplitudes. 
+The main goal is to provide a simple interface to build decay chains and their amplitudes, which can be used in amplitude analyses. 
+
+## Online Decay Editor
+
+There is a beta version of a web based decay editor, which is hosted [here](https://kaihabermann.github.io/DecaySelector/).
+The Website allows for an easy selection of a decay and resonances. Once finished a script generating an amplitude with `decayamplitude` can be downloaded.
+This is usually the easiest and quickest way to get a working amplitude. Explicit lineshapes need then to be defined by the user, where it is marked in the downloaded script.
+
+## Usage
+```python
+from decayamplitude.resonance import Resonance
+from decayamplitude.rotation import QN, Angular
+from decayamplitude.chain import DecayChain, MultiChain
+from decayamplitude.combiner import ChainCombiner
+
+
+
+
+from decayangle.decay_topology import Topology, Node, TopologyCollection
+
+# First we define the final state
+final_state_qn = {
+        1: QN(1, 1),
+        2: QN(2, 1),
+        3: QN(0, 1)
+    }
+
+# decayangles Topology class is used to generate the angular variables. Be carefull here, as fit results may depend on the ordering. 
+
+topology1 = Topology(
+    0,
+    decay_topology=((2,3), 1)
+)
+topology2 = Topology(
+    0,
+    decay_topology=((1, 2), 3)
+)
+
+# alternatively we can use the topology collection to define all topologies automatically
+tg = TopologyCollection(
+    0,
+    [1,2,3]
+)
+tg.topologies
+```
+
+We now have a basic definition of our decay scheme. But we need resonances to react. In general for a multi body decay we want to define a list of resonances for each isobar. Then let the code figure out all the possible decay chains.
+
+```python
+resonances1 = {
+    # we need to define resonances for each internal node of the decay chain
+    # A resonance needs a node, to which it couples, quantum numbers, a lineshape
+    # and a list of argument names, which will be used to map the parameters of the resonance 
+    # to the outside, once all our configurations are combined into an amplitude
+    (2,3): Resonance(topology1.nodes[(2, 3)], 
+                    quantum_numbers=QN(0, -1), 
+                    lineshape=BW_lineshape(topology1.nodes[(2, 3)].mass(momenta)), 
+                    argnames=["gamma1", "m01"]),
+
+    # since we can not only model decays, but also transitions from 2 particle
+        # to many particles
+    # Thus we may have to model multiple initial resonances and their production
+        # with a lineshape
+    # For decays we can use a constant lineshape 
+    # The preserve_parity flag controlls which L S couplings will be produced, 
+        # if one uses the automated generation of the possible couplings
+    # This has no effect if one plugs in couplings by hand
+    0: Resonance(Node(0), quantum_numbers=QN(1, 1),
+    lineshape=constant_lineshape, 
+    argnames=[], 
+    preserve_partity=False)
+
+# we use the argnames, to use the same mass for both BW lineshapes, but different widths
+resonances2 = {
+    (1, 2): Resonance(nodes_2[(1, 2)], quantum_numbers=QN(3, -1), lineshape=BW_lineshape(nodes_2[(1, 2)].mass(momenta)), argnames=["gamma2", "m01"]),
+    0: Resonance(Node(0), quantum_numbers=QN(1, 1), lineshape=constant_lineshape, argnames=[], preserve_partity=False)
+    }
+}
+```
+
+Now we can take the resonance dictionaries and combine them with a topology in order to produce a `DecayChain`. 
+
+```python
+chain1 = DecayChain(topology = topology1,
+        resonances = resonances1,
+        momenta = momenta,
+        final_state_qn = final_state_qn)
+
+chain2 = DecayChain(topology = topology2,
+        resonances = resonances2,
+        momenta = momenta,
+        final_state_qn = final_state_qn)
+```
+These chains are already able to produce a chain function, which can be evaluated for a given set of parameters. 
+
+```python
+chain1.chain_function
+```
+
+We can now combine the chains into a `ChainCombiner` object. This object will internally take care of the alignmeht operations.
+
+```python
+combined = ChainCombiner([chain1, chain2])
+
+# we can generate the unpolarized amplitude
+unpolarized, argnames = combined.unpolarized_amplitude(combined.generate_couplings())
+# unpolarized(*args) will return the amplitude for the given parameters
+
+# we can generate the matix elements depending on the polarization of the particles
+polarized, lambdas, argnames = combined.polarized_amplitude(combined.generate_couplings())
+# polarized(*lambdas, *args) will return the amplitude for the given parameters and polarization
+
+# here we get a list of aditional function parameters, which represent the polarization of the initial and final state particles
+# lambdas = ["h_0", "h_1", "h_2", "h_3"]
+
+# alternatively we can produce all matrix elements at once
+matrx_function, matrix_argnames = combined.matrix_function(combined.generate_couplings())
+# here we only have the initial state polarization as an additional parameter
+# matrix_argnames = ["h_0"] + argnames
+# matrx_function(h_0, *args) will return the amplitude for the given parameters and polarization
+
+```
+
+## Related projects
+
+Amplitude analyses dealing with non-zero spin of final-state particles have to implement wigner rotations in some way.
+However, there are a few projects addressing these rotations explicitly using analytic expressions in [DPD paper](https://inspirehep.net/literature/1758460), derived for three-body decays:
+
+- [ThreeBodyDecays.jl](https://github.com/mmikhasenko/ThreeBodyDecays.jl),
+- [SymbolicThreeBodyDecays.jl](https://github.com/mmikhasenko/SymbolicThreeBodyDecays.jl),
+- [ComPWA/ampform-dpd](https://github.com/ComPWA/ampform-dpd).
+
+## How to cite
+
+This software package as well as the closely related [decayangle](https://github.com/KaiHabermann/decayangle) should be cited by the accompaning paper
+[Wigner Rotations for Cascade Reactions](https://doi.org/10.1103/PhysRevD.111.056015)
+
+## License
+
+`decayamplitude` is distributed under the terms of the [MIT](https://mit-license.org/) license.

decayamplitude-0.1.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

decayamplitude-0.1.0/docs/conf.py

@@ -0,0 +1,29 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os, sys
+
+sys.path.insert(0, os.path.abspath("../src/"))
+project = "decayamplitude"
+copyright = "2025, Kai Habermann"
+author = "Kai Habermann"
+release = "09.02.2025"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_mdinclude"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

decayamplitude-0.1.0/docs/index.rst

@@ -0,0 +1,23 @@
+.. decayamplitude documentation master file, created by
+   sphinx-quickstart on Tue Apr  2 16:09:04 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. Welcome to decayamplitude's documentation!
+.. ======================================
+
+.. automodule:: decayamplitude
+    :members:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. mdinclude:: ../README.md
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

decayamplitude-0.1.0/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd