decaylanguage 0.9.1

A language to describe particle decays, and tools to work with them.

<a href="https://decaylanguage.readthedocs.io/en/latest/"><img align="left" src="https://raw.githubusercontent.com/scikit-hep/decaylanguage/master/images/DecayLanguage.png"></img></a><br>

DecayLanguage implements a language to describe and convert particle decays between digital representations, effectively making it possible to interoperate several fitting programs. Particular interest is given to programs dedicated to amplitude analyses.

DecayLanguage provides tools to parse so-called .dec decay files, and describe, manipulate and visualize decay chains.

Installation

Just run the following:

pip install decaylanguage

You can use a virtual environment through pipenv or with --user if you know what those are. Python 2.7 and 3.4+ are supported.

Dependencies: (click to expand)

Required and compatibility dependencies will be automatically installed by pip.

Required dependencies:

• particle: PDG particle data and identification codes
• Numpy: The numerical library for Python
• pandas: Tabular data in Python
• attrs: DataClasses for Python
• plumbum: Command line tools
• lark-parser: A modern parsing library for Python

Python compatibility:

• six: Compatibility library
• pathlib2 backport if using Python 2.7
• enum34 backport if using Python /< 3.5
• importlib_resources backport if using Python /< 3.7

Recommended dependencies:

• graphviz to render (DOT language) graph descriptions of decay chains.
• pydot, a Python interface to Graphviz's Dot language, used to visualize particle decay chains.

Getting started

The Binder demo is an excellent way to get started with DecayLanguage.

This is a quick user guide. For a full API docs, go here (note that it is presently work-in-progress).

What is DecayLanguage?

DecayLanguage is a set of tools for building and transforming particle decays:

1. It provides tools to parse so-called .dec decay files, and describe, manipulate and visualize the resulting decay chains.

2. It implements a language to describe and convert particle decays between digital representations, effectively making it possible to interoperate several fitting programs. Particular interest is given to programs dedicated to amplitude analyses.

Particles

Particles are a key component when dealing with decays. Refer to the particle package for how to deal with particles and Monte Carlo particle identification codes.

Parse decay files

Decay .dec files can be parsed simply with

from decaylanguage import DecFileParser

parser = DecFileParser('my-decay-file.dec')
parser.parse()

# Inspect what decays are defined
parser.list_decay_mother_names()

# Print decay modes, etc. ...

A copy of the master DECAY.DEC file used by the LHCb experiment is provided here for convenience.

The DecFileParser class implements a series of methods giving access to all information stored in decay files: the decays themselves, particle name aliases, definitions of charge-conjugate particles, variable and Pythia-specific definitions, etc.

It can be handy to parse from a multi-line string rather than a file:

s = """Decay pi0
0.988228297   gamma   gamma                   PHSP;
0.011738247   e+      e-      gamma           PI0_DALITZ;
0.000033392   e+      e+      e-      e-      PHSP;
0.000000065   e+      e-                      PHSP;
Enddecay
"""

dfp = DecFileParser.from_string(s)
dfp.parse()

Advanced usage

The list of .dec file decay models known to the package can be inspected via

from decaylanguage.dec import known_decay_models

Say you have to deal with a decay file containing a new model not yet on the list above. Running the parser as usual will result in a UnexpectedToken exception. It is nevertheless easy to deal with this issue; no need to wait for a new release. It is just a matter of adding the model name to the list in decaylanguage/data/decfile.lark (or your private copy), see the line MODEL_NAME.2 : "BaryonPCR"|"BTO3PI_CP"|"BTOSLLALI"|..., and then proceed as usual apart from adding an extra line to call to load_grammar to specify the Lark grammar to use:

dfp = DecFileParser('my_decfile.dec')
dfp.load_grammar('path/to/my_updated_decfile.lark')
dfp.parse()
...

This being said, please do submit a pull request to add new models, if you spot missing ones ...

Visualize decay files

The class DecayChainViewer allows the visualization of parsed decay chains:

from decaylanguage import DecayChainViewer

# Build the (dictionary-like) D*+ decay chain representation setting the D+ and D0 mesons to stable,
# to avoid too cluttered an image
d = dfp.build_decay_chains('D*+', stable_particles=['D+', 'D0'])
DecayChainViewer(d)  # works in a notebook

The actual graph is available as

# ...
dcv = DecayChainViewer(d)
dcv.graph

making all pydot.Dot class properties and methods available, such as

dcv.graph.write_pdf('mygraph.pdf')

In the same way, all pydot.Dot class attributes are settable upon instantiation of DecayChainViewer:

dcv = DecayChainViewer(chain, graph_name='TEST', rankdir='TB')

Universal representation of decay chains

A series of classes and methods have been designed to provide universal representations of particle decay chains of any complexity, and to provide the ability to convert between these representations. Specifically, class- and dictionary-based representations have been implemented.

An example of a class-based representation of a decay chain is the following:

>>> from decaylanguage import DaughtersDict, DecayMode, DecayChain
>>>
>>> dm1 = DecayMode(0.0124, 'K_S0 pi0', model='PHSP')
>>> dm2 = DecayMode(0.692, 'pi+ pi-')
>>> dm3 = DecayMode(0.98823, 'gamma gamma')
>>> dc = DecayChain('D0', {'D0':dm1, 'K_S0':dm2, 'pi0':dm3})
>>> dc
<DecayChain: D0 -> K_S0 pi0 (2 sub-decays), BF=0.0124>

Decay chains can be visualised with the DecayChainViewer class making use of the dictionary representation dc.to_dict(), which is the simple representation understood by DecayChainViewer, as see above:

DecayChainViewer(dc.to_dict())

The fact that 2 representations of particle decay chains are provided ensures the following:

1. Human-readable (class) and computer-efficient (dictionary) alternatives.
2. Flexibility for parsing, manipulation and storage of decay chain information.

Decay modeling

The most common way to create a decay chain is to read in an AmpGen style syntax from a file or a string. You can use:

from decaylanguage.modeling import AmplitudeChain
lines, parameters, constants, states = AmplitudeChain.read_ampgen(text='''
EventType D0 K- pi+ pi+ pi-

D0[D]{K*(892)bar0{K-,pi+},rho(770)0{pi+,pi-}}                            0 1 0.1 0 1 0.1

K(1460)bar-_mass  0 1460 1
K(1460)bar-_width 0  250 1

a(1)(1260)+::Spline::Min 0.18412
a(1)(1260)+::Spline::Max 1.86869
a(1)(1260)+::Spline::N 34
''')

Here, lines will be a list of AmplitudeChain lines (pretty print supported in Jupyter notebooks), parameters will be a table of parameters (ranged parameters not yet supported), constants will be a table of constants, and states will be the list of known states (EventType).

Converters

You can output to a format (currently only GooFit supported, feel free to make a PR to add more). Use a subclass of DecayChain, in this case, GooFitChain. To use the GooFit output, type from the shell:

python -m decaylanguage -G goofit myinput.opts

Acknowledgements

Support for this work was provided by the National Science Foundation cooperative agreement OAC-1450377 (DIANA/HEP) and OAC-1836650 (IRIS-HEP). Any opinions, findings, conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation.

Changelog

Version 0.9.1 (2020-11-04)

• Parsing of decay files (aka .dec files):
  • DecFileParser class enhanced to understand the CopyDecay statement.
• Tests:
  • Added tests for Python 3.8 and 3.9 on Windows.
• Miscellaneous:
  • Conda badge added to the README, since package now available in Conda.

Version 0.9.0 (2020-10-31)

• Dependencies and Python version support:
  • Package dependent on Particle version 0.13.
  • Support for Python 3.9 added.

Version 0.8.0 (2020-09-29)

• Dependencies:
  • Package dependent on Particle version 0.12.

Version 0.7.0 (2020-08-13)

• Dependencies:
  • Package dependent on Particle version 0.11.
  • Dependencies on lark-parser and others upgraded.

Version 0.6.2 (2020-06-05)

• Dependencies:
  • Package dependency on pydot made a requirement.

Version 0.6.1 (2020-01-15)

• Parsing of decay files (aka .dec files):
  • Simpifications in various methods of class DecFileParser.
  • A couple more tests added.
• Minor fixes.

Version 0.6.0 (2020-01-10)

• Parsing of decay files (aka .dec files):
  • Master Belle II DECAY.DEC file added to the package.
  • Certain DecFileParser class methods made more versatile.
  • Lark parsing grammar file improved.
• Universal representation of decay chains:
  • Classes DecayChain, DecayMode, DaughtersDict and DecayChainViewer enhanced.
• Dependencies and Python version support:
  • Package dependent on Particle versions 0.9.*.
  • Support for Python 3.8 added.

Version 0.5.3 (2019-10-28)

• Dict-like representation of particle decay chains improved.
• Documentation added to README.

Version 0.5.2 (2019-10-23)

• Parsing of decay files (aka .dec files):
  • New Belle II decay models added.
• README updated to provide basic coverage of recent new features.
• Clean-up of obsolete files.

Version 0.5.1 (2019-10-14)

• Universal representation of decay chains:
  • Classes DecayChain and DecayMode enhanced.
  • Tests for class DecayChain added.
• Parsing of decay files (aka .dec files):
  • DecFileParser class extended.

Version 0.5.0 (2019-10-11)

• Universal representation of decay chains:
  • Class DecayChain introduced.
  • Classes DaughtersDict and DecayMode enhanced.
• Changes in API:
  • DecFileParser.build_decay_chain() renamed to DecFileParser.build_decay_chains().
• Package dependent on Particle package version 0.6.

Version 0.4.0 (2019-09-02)

• Package dependent on Particle version 0.6.0. Otherwise identical to version 0.3.2.

Version 0.3.2 (2019-08-29)

• Parsing of decay files (aka .dec files):
  • DecFileParser class extended to understand JETSET definitions.
• Visualisation of decay chains:
  • DecayChainViewer class simplified and improved.
  • Decay chain DOT graphs now display HTML particle names.
  • More tests.

Version 0.3.1 (2019-07-18)

• Parsing of decay files (aka .dec files):
  • Update to latest LHCb DECAY.DEC file.
• Visualisation of decay chains:
  • DecayChainViewer class made more robust.
  • Better tests.
• Miscellaneous:
  • Demo notebook updated.
  • README updated with latest package functionality.
  • Python wheels generation added.
  • Zenodo DOI badge added to README.

Version 0.3.0 (2019-06-26)

• Decays modelling:
  • Updates to Mint related particle data files.
• Parsing of decay files (aka .dec files):
  • Lark parser files added, for .dec decay files.
  • DecFileParser class introduced, with documentation and test suite.
  • Various .dec test decay files added.
• Visualisation of decay chains:
  • DecayChainViewer class introduced, with documentation and test suite.
• Universal representation of decay chains:
  • First "building block" classes DaughtersDict and DecayMode introduced, with documentation and test suite.
• Package dependencies:
  • Package made dependent on Scikit-HEP's Particle package.
  • Redundant code removed.
• Continuous integration:
  • CI with Azure pipelines introduced.
  • CI with Travis and AppVeyor removed.
• Miscellaneous:
  • Demo notebook added, with a launcher for Binder.
  • Copyright statements added to repository files.
  • General clean-up and minor bug fixes.

Version 0.2.0 (2018-08-02)

• First release as part of Scikit-HEP.
• Using new data package with importlib_resources (or importlib.resources on Python 3.7).
• Better docs and examples.
• Some method renaming.
• Generalized converter script.

Version 0.1.0 (2018-03-13)

• First release on PyPI.