decaylanguage 0.13.0__py3-none-any.whl

DecayLanguage-0.13.0.dist-info/LICENSE

@@ -0,0 +1,23 @@
+BSD 3-Clause License
+
+Copyright (c) 2018-2021, Eduardo Rodrigues and Henry Schreiner.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
+conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+  disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

DecayLanguage-0.13.0.dist-info/METADATA

@@ -0,0 +1,320 @@
+Metadata-Version: 2.1
+Name: DecayLanguage
+Version: 0.13.0
+Summary: A language to describe, manipulate and convert particle decays
+Home-page: https://github.com/scikit-hep/decaylanguage
+Author: Eduardo Rodrigues, Henry Fredrick Schreiner III
+Author-email: eduardo.rodrigues@cern.ch, henry.schreiner@cern.ch
+Maintainer: The Scikit-HEP admins
+Maintainer-email: scikit-hep-admins@googlegroups.com
+License: BSD-3-Clause
+Keywords: HEP,particle,decay,chain,representation
+Platform: Any
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs (>=19.2)
+Requires-Dist: deprecated
+Requires-Dist: graphviz
+Requires-Dist: lark-parser (>=0.11.0)
+Requires-Dist: numpy (>=1.12)
+Requires-Dist: pandas (>=0.22)
+Requires-Dist: particle (==0.16.*)
+Requires-Dist: plumbum (>=1.6.9)
+Requires-Dist: importlib-resources (>=2.0) ; python_version < "3.9"
+Provides-Extra: dev
+Requires-Dist: pytest (>=6) ; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest (>=6) ; extra == 'test'
+Requires-Dist: pytest-cov ; extra == 'test'
+
+<img alt="DecayLanguage logo" src="https://raw.githubusercontent.com/scikit-hep/decaylanguage/master/images/DecayLanguage.png"/>
+
+# DecayLanguage: describe, manipulate and convert particle decays
+
+[![Scikit-HEP](https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg)](https://scikit-hep.org/)
+[![PyPI Package latest release](https://img.shields.io/pypi/v/decaylanguage.svg)](https://pypi.python.org/pypi/decaylanguage)
+[![Conda latest release](https://img.shields.io/conda/vn/conda-forge/decaylanguage.svg)](https://anaconda.org/conda-forge/decaylanguage)
+[![Supported versions](https://img.shields.io/pypi/pyversions/decaylanguage.svg)](https://pypi.python.org/pypi/decaylanguage)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3257423.svg)](https://doi.org/10.5281/zenodo.3257423)
+
+[![GitHub Actions Status: CI](https://github.com/scikit-hep/decaylanguage/workflows/CI/badge.svg)](https://github.com/scikit-hep/decaylanguage/actions)
+[![Code Coverage](https://codecov.io/gh/scikit-hep/decaylanguage/graph/badge.svg?branch=master)](https://codecov.io/gh/scikit-hep/decaylanguage?branch=master)
+[![Documentation Status](https://readthedocs.org/projects/decaylanguage/badge/?style=flat)](https://readthedocs.org/projects/decaylanguage)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+[![Binder demo](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/scikit-hep/decaylanguage/master?urlpath=lab/tree/notebooks/DecayLanguageDemo.ipynb)
+
+
+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:
+
+```bash
+pip install decaylanguage
+```
+
+You can use a virtual environment through pipenv or with `--user` if you know
+what those are. [Python
+3.6+](http://docs.python-guide.org/en/latest/starting/installation) supported
+(see version 0.12 for Python 2 & 3.5 support).
+
+<details><summary>Dependencies: (click to expand)</summary><p>
+
+Required and compatibility dependencies will be automatically installed by pip.
+
+### Required dependencies:
+
+-   [particle](https://github.com/scikit-hep/particle): PDG particle data and identification codes
+-   [NumPy](https://scipy.org/install.html): The numerical library for Python
+-   [pandas](https://pandas.pydata.org/): Tabular data in Python
+-   [attrs](https://github.com/python-attrs/attrs): DataClasses for Python
+-   [plumbum](https://github.com/tomerfiliba/plumbum): Command line tools
+-   [lark-parser](https://github.com/lark-parser/lark): A modern parsing library for Python
+-   [graphviz](https://gitlab.com/graphviz/graphviz/) to render (DOT language) graph
+    descriptions and visualizations of decay chains.
+
+### Python compatibility:
+-   [importlib_resources](http://importlib-resources.readthedocs.io/en/latest/) backport if using Python /< 3.7
+</p></details>
+
+
+## Getting started
+
+The [Binder demo](https://mybinder.org/v2/gh/scikit-hep/decaylanguage/master?urlpath=lab/tree/notebooks/DecayLanguageDemo.ipynb)
+is an excellent way to get started with `DecayLanguage`.
+
+This is a quick user guide. For a full API docs, go [here](https://decaylanguage.readthedocs.io/en/latest/)
+(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](https://github.com/scikit-hep/particle)
+for how to deal with particles and Monte Carlo particle identification codes.
+
+### Parse decay files
+
+Decay `.dec` files can be parsed simply with
+
+```python
+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](https://github.com/scikit-hep/decaylanguage/tree/master/decaylanguage/data)
+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:
+
+```python
+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
+
+```python
+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:
+
+```python
+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:
+
+```python
+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
+```
+
+![DecayChain D*](https://raw.githubusercontent.com/scikit-hep/decaylanguage/master/images/DecayChain_Dst_stable-D0-and-D+.png)
+
+The actual graph is available as
+
+```python
+# ...
+dcv = DecayChainViewer(d)
+dcv.graph
+```
+
+making all `graphviz.dot.Digraph` class properties and methods available, such as
+
+```python
+dcv.graph.render(filename='mygraph', format='pdf', view=True, cleanup=True)
+```
+
+In the same way, all `graphviz.dot.Digraph` class attributes are settable
+upon instantiation of `DecayChainViewer`:
+
+```python
+dcv = DecayChainViewer(chain, name='TEST', format='pdf')
+```
+
+### 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:
+
+```python
+>>> 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:
+
+```python
+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:
+
+```python
+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:
+
+```bash
+python -m decaylanguage -G goofit myinput.opts
+```
+
+## Acknowledgements
+
+The 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.
+
+
+[AmpGen]: https://gitlab.cern.ch/lhcb/Gauss/tree/LHCBGAUSS-1058.AmpGenDev/Gen/AmpGen
+[GooFit]: https://GooFit.github.io
+
+

DecayLanguage-0.13.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+decaylanguage/__init__.py,sha256=m_luI0KvpAvCVDhBLxTwf9ObW0SGMFnu39mq61_ftOo,695
+decaylanguage/__main__.py,sha256=5C2gWnFbfvDVC0mdnp7YnhHZB8lJhX6TArO-LM49oVs,641
+decaylanguage/_version.py,sha256=YoxiEd2a3_SXwX-vRnmgSRH4ZrUvGq7JwQJpvV0eLYI,144
+decaylanguage/data/DECAY_BELLE2.DEC,sha256=hZcGcK941-FvnSLfZwBvrGFVPiGOkTqQZKRo4eLA8xg,513709
+decaylanguage/data/DECAY_LHCB.DEC,sha256=lAm_rGHiuYFv3JlFZqt3_DE0rX1CZi85S4o6yFqdECs,559864
+decaylanguage/data/MintDalitzSpecialParticles.csv,sha256=pd-mZwHyp3Nigul4EbCGz2R5kHVh0GTelEBZfb-DjlY,3050
+decaylanguage/data/MintDalitzSpecialParticles.fwf,sha256=RtAw_V7btv3XJkdzGvfbmVKJFZ7biv2ecfJ28mrhy2Q,4331
+decaylanguage/data/MintDalitzSpecialParticlesLatex.csv,sha256=lsWdKUbTx5RuLf5cjkqcpPteJYUtlt4I5qSvb2xw_Jw,631
+decaylanguage/data/README.rst,sha256=esV_9BydY7tTx1fdVXeY16LkHkqx0tFoaemRT8AZB0A,1661
+decaylanguage/data/WorkingOutModel.ipynb,sha256=JNNN5vB1jNvZIrAdHqIO8xBOlM3XoYSsJabB5yubKzM,24969
+decaylanguage/data/__init__.py,sha256=kbsVo92He4TppyLjTiRWg4jQLj9sNQzT7tTRS6XuzsQ,369
+decaylanguage/data/ampgen.lark,sha256=Xlq7T62BRPPc0GI6mFqrBTMElDwRl1lUHu6_p74xsXY,1663
+decaylanguage/data/decfile.lark,sha256=8qJytSMx8qQU0x3xTbY85rSbAVN8P0-gMUczq7Ws4l0,2603
+decaylanguage/data/particle.lark,sha256=p0ysF8WfUnbiviS5xoJrIX_cGIftk2KzczRbjm_BRNY,568
+decaylanguage/dec/__init__.py,sha256=Udlpg_i94haCHgQWeZy2zNci-fAJ8gNDUyhgFMMa8fw,156
+decaylanguage/dec/dec.py,sha256=jtdlthWZq55-dGY__l1NERiKmKVnS_S39iQ7nV2YzpE,50840
+decaylanguage/dec/decparser.py,sha256=waEt2CMWz0fAdvR8HhVhcEQzkXexA9RHH7PGGkUVZW8,13130
+decaylanguage/dec/enums.py,sha256=uJZVTRo-1mckL6uIWlCVvbNh7TZYGWdmdbQ61xD4R6Q,1689
+decaylanguage/decay/__init__.py,sha256=8fpZ23K6zYO1G6RAYEiAL7TwSsFqW8l5H1EXq7V2aM0,205
+decaylanguage/decay/decay.py,sha256=mI9VXcSPBwqa1L6k7uJpH6pbF9bG-ts1i9yW6eiKn8U,22272
+decaylanguage/decay/viewer.py,sha256=f4-8Ypl01ZQaXJU4D99tgn0VVdUJi2uTchnIJfhFlsI,8754
+decaylanguage/modeling/AmpGenReader.ipynb,sha256=VYMSvKod94xgtv47_DdPNSO9Gw8dfI40fR9rrOLmQGY,95387
+decaylanguage/modeling/__init__.py,sha256=zNe-37vLf2KDB8Id2hU0XxARaNJ3J3qrOfLyhu8Lhug,119
+decaylanguage/modeling/ampgen2goofit.py,sha256=QeA_RWFw56T0jpiFYBrztZKNFMy4l-mEJJxrJqqI8n8,2588
+decaylanguage/modeling/ampgentransform.py,sha256=N5OYfkcw8N2wlI-vnoPq8jYwI9_mtzOw-mMfj0JuXYY,2007
+decaylanguage/modeling/amplitudechain.py,sha256=YDwn3mjv72Xd74F1B39HRB1EG8Mc-IQp6DYWRH3C_eE,9249
+decaylanguage/modeling/decay.py,sha256=YmEZ13hzyxS_zNBAivdY9IaDf_RGaNhqQxxKEO5t8C4,3364
+decaylanguage/modeling/goofit.py,sha256=FT5LjGIaoXBCx2NP-kfS0HpxmjoxcZA8dMRUwmt45EI,14409
+decaylanguage/utils/__init__.py,sha256=fBB_EO3S9kw4g9DMnX4FCEQuwY80jwdWzZbeGGC1x90,290
+decaylanguage/utils/errors.py,sha256=fGh691RiECMyuevn7YBCTOBTWWj0JOZR1An9bMcxF5g,327
+decaylanguage/utils/particleutils.py,sha256=g3ve_kbD85Uk4dR2KgHDhqwCKKNWPW0WVqkEmLplax8,2073
+decaylanguage/utils/utilities.py,sha256=EuHHkcjV6qOUh1zAFgptIHe0E8c6dgmJ81EGeJYj3UE,1332
+DecayLanguage-0.13.0.dist-info/LICENSE,sha256=wG2bR7fBVvAMPl8eOdbRHhqEOfK5ZEBW3s4OdD5Zps4,1537
+DecayLanguage-0.13.0.dist-info/METADATA,sha256=XujEY-8hOKhQiWuuSYYPDRFPVAl3wX5f-3lw78eUUfA,12062
+DecayLanguage-0.13.0.dist-info/WHEEL,sha256=ewwEueio1C2XeHTvT17n8dZUJgOvyCWCt0WVNLClP9o,92
+DecayLanguage-0.13.0.dist-info/top_level.txt,sha256=Fq3n0TJQ7UcfVnSNXtu9F0cGIJJZOBsZ2lyQMOgJfOU,14
+DecayLanguage-0.13.0.dist-info/RECORD,,

DecayLanguage-0.13.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.37.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

DecayLanguage-0.13.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+decaylanguage

decaylanguage/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2018-2021, Eduardo Rodrigues and Henry Schreiner.
+#
+# Distributed under the 3-clause BSD license, see accompanying file LICENSE
+# or https://github.com/scikit-hep/decaylanguage for details.
+
+
+# Convenient access to the version number
+from ._version import version as __version__
+
+# Direct access to decay file parsing tools
+from .dec import DecFileParser
+
+# Direct access to decay chain representation classes and visualization tools
+from .decay import DaughtersDict, DecayChain, DecayChainViewer, DecayMode
+
+__all__ = (
+    "__version__",
+    "DecFileParser",
+    "DecayChainViewer",
+    "DaughtersDict",
+    "DecayMode",
+    "DecayChain",
+)
+
+
+def __dir__():
+    return __all__

decaylanguage/__main__.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python
+# Copyright (c) 2018-2021, Eduardo Rodrigues and Henry Schreiner.
+#
+# Distributed under the 3-clause BSD license, see accompanying file LICENSE
+# or https://github.com/scikit-hep/decaylanguage for details.
+
+
+from plumbum import cli
+
+from decaylanguage.modeling.ampgen2goofit import ampgen2goofit
+
+
+class DecayLanguageDecay(cli.Application):
+    generator = cli.SwitchAttr(["-G", "--generator"], cli.Set("goofit"), mandatory=True)
+
+    def main(self, filename):
+        if self.generator == "goofit":
+            ampgen2goofit(filename)
+
+
+def main():
+    DecayLanguageDecay.run()
+
+
+if __name__ == "__main__":
+    main()

decaylanguage/_version.py

@@ -0,0 +1,5 @@
+# coding: utf-8
+# file generated by setuptools_scm
+# don't change, don't track in version control
+version = '0.13.0'
+version_tuple = (0, 13, 0)