Package: decaylanguage
DecayLanguage: describe, manipulate and convert particle decaysDecayLanguage 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.InstallationJust run the following:pipinstalldecaylanguageYou can use a virtual environment through pipenv or with--userif you know
what those are.Python
3.7+supported
(see version 0.12 for Python 2 & 3.5 support, 0.14 for Python 3.6 support).Dependencies: (click to expand)Required and compatibility dependencies will be automatically installed by pip.Required dependencies:particle: PDG particle data and identification codesNumPy: The numerical library for Pythonpandas: Tabular data in Pythonattrs: DataClasses for Pythonplumbum: Command line toolslark: A modern parsing library for Pythongraphvizto render (DOT language) graph
descriptions and visualizations of decay chains.Python compatibility:importlib_resourcesbackport if using Python /< 3.7Getting startedTheBinder demois an excellent way to get started withDecayLanguage.This is a quick user guide. For a full API docs, gohere(note that it is presently work-in-progress).What is DecayLanguage?DecayLanguageis a set of tools for building and transforming particle
decays:It provides tools to parse so-called.decdecay files,
and describe, manipulate and visualize the resulting decay chains.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.ParticlesParticles are a key component when dealing with decays.
Refer to theparticle packagefor how to deal with particles and Monte Carlo particle identification codes.Parse decay filesDecay.decfiles can be parsed simply withfromdecaylanguageimportDecFileParserparser=DecFileParser('my-decay-file.dec')parser.parse()# Inspect what decays are definedparser.list_decay_mother_names()# Print decay modes, etc. ...A copy of the master DECAY.DEC file used by the LHCb experiment is providedherefor convenience.TheDecFileParserclass 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 pi00.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 usageThe list of.decfile decay models known to the package can be inspected viafromdecaylanguage.decimportknown_decay_modelsSay 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 an error in the model parsing.
It is nevertheless easy to deal with this issue; no need to wait for a new release:
Just callload_additional_decay_modelswith the models you'd like to add as arguments
before parsing the file:dfp=DecFileParser('my_decfile.dec')dfp.load_additional_decay_models("MyModel1","MyModel2")dfp.parse()...This being said, please do submit a pull request to add new models,
if you spot missing ones ...Visualize decay filesThe classDecayChainViewerallows the visualization of parsed decay chains:fromdecaylanguageimportDecayChainViewer# Build the (dictionary-like) D*+ decay chain representation setting the# D+ and D0 mesons to stable, to avoid too cluttered an imaged=dfp.build_decay_chains('D*+',stable_particles=('D+','D0'))DecayChainViewer(d)# works in a notebookThe actual graph is available as# ...dcv=DecayChainViewer(d)dcv.graphmaking allgraphviz.Digraphclass properties and methods available, such asdcv.graph.render(filename='mygraph',format='pdf',view=True,cleanup=True)In the same way, allgraphviz.Digraphclass attributes are settable
upon instantiation ofDecayChainViewer:dcv=DecayChainViewer(chain,name='TEST',format='pdf')Universal representation of decay chainsA 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:>>>fromdecaylanguageimportDaughtersDict,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_S0pi0(2sub-decays),BF=0.0124>Decay chains can be visualised with theDecayChainViewerclass making use
of the dictionary representationdc.to_dict(), which is the simple
representation understood byDecayChainViewer, as see above:DecayChainViewer(dc.to_dict())The fact that 2 representations of particle decay chains are provided ensures
the following:Human-readable (class) and computer-efficient (dictionary) alternatives.Flexibility for parsing, manipulation and storage of decay chain information.Decay modelingThe most common way to create a decay chain is to read in anAmpGenstyle syntax from a file or a string. You can use:fromdecaylanguage.modelingimportAmplitudeChainlines,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.1K(1460)bar-_mass  0 1460 1K(1460)bar-_width 0  250 1a(1)(1260)+::Spline::Min 0.18412a(1)(1260)+::Spline::Max 1.86869a(1)(1260)+::Spline::N 34''')Here,lineswill be a list of AmplitudeChain lines (pretty print supported in Jupyter notebooks),parameterswill be a table of parameters (ranged parameters not yet supported),constantswill be a table of constants,
andstateswill be the list of known states (EventType).ConvertersYou can output to a format (currently onlyGooFitsupported, feel free
to make a PR to add more). Use a subclass of DecayChain, in this case,
GooFitChain. To use theGooFitoutput, type from the shell:python-mdecaylanguage-Ggoofitmyinput.optsContributorsWe hereby acknowledge the contributors that made this project possible (emoji key):Eduardo Rodrigues🚧💻📖Henry Schreiner🚧💻📖Yipeng Sun💻Chris Burr📖Kilian Lieret📖Moritz Bauer💻FlorianReiss💻📖Adam Morris💻Dazhi Wang💻This project follows theall-contributorsspecification.AcknowledgementsThe UK Science and Technology Facilities Council (STFC) and the University of Liverpool
provide funding for Eduardo Rodrigues (2020-) to work on this project part-time.Support for this work was provided by the National Science Foundation
cooperative agreement OAC-1450377 (DIANA/HEP) in 2016-2019
and has been provided by OAC-1836650 (IRIS-HEP) since 2019.
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.