Metadata-Version: 2.1
Name: DecayLanguage
Version: 0.7.2
Summary: A language to describe particle decays, and tools to work with them.
Home-page: https://github.com/scikit-hep/decaylanguage
Author: Henry Fredrick Schreiner III, Eduardo Rodrigues
Author-email: henry.schreiner@cern.ch, eduardo.rodrigues@cern.ch
Maintainer: The Scikit-HEP admins
Maintainer-email: scikit-hep-admins@googlegroups.com
License: BSD 3-Clause License
Description: 
            <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:
        
        ```bash
        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+](http://docs.python-guide.org/en/latest/starting/installation) are supported.
        
        <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
        
        ### Python compatibility:
        -   [six](https://github.com/benjaminp/six): Compatibility library
        -   [pathlib2](https://github.com/mcmtroffaes/pathlib2) backport if using Python 2.7
        -   [enum34](https://bitbucket.org/stoneleaf/enum34) backport if using Python /< 3.5
        -   [importlib_resources](http://importlib-resources.readthedocs.io/en/latest/) backport if using Python /< 3.7
        
        
        ### Recommended dependencies:
        -   [graphviz](https://gitlab.com/graphviz/graphviz/) to render (DOT
            language) graph descriptions of decay chains.
        -   [pydot](https://github.com/pydot/pydot), a Python interface to
            Graphviz's Dot language, used to visualize particle decay chains.
        </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 `pydot.Dot` class properties and methods available, such as
        
        ```python
        dcv.graph.write_pdf('mygraph.pdf')
        ```
        
        In the same way, all `pydot.Dot` class attributes are settable
        upon instantiation of `DecayChainViewer`:
        
        ```python
        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:
        
        ```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
        
        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.
        
        
        [AmpGen]: https://gitlab.cern.ch/lhcb/Gauss/tree/LHCBGAUSS-1058.AmpGenDev/Gen/AmpGen
        [GooFit]: https://GooFit.github.io
        
        
        # Changelog
        
        ## 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.
        
Keywords: HEP,particle,decay,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 :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Description-Content-Type: text/markdown
Provides-Extra: test
Provides-Extra: notebook
