Add several methods to handle decay descriptors

[admorris]

Closes #332

Partly implements #200

Features

• Add function _expand_decay_modes to the decay module: it takes a DecayChainDict and returns a list of strings corresponding to all possible decay descriptors in the dict.
  • NB: the passed dict is heavily modified in the process
• Add DecayChain.to_string() which represents the full decay chain as a single-line string, e.g.:

>>> dm1 = DecayMode(0.6770, "D0 pi+") # D*+
>>> dm2 = DecayMode(0.0124, "K_S0 pi0") # D0
>>> dm3 = DecayMode(0.692, "pi+ pi-") # K_S0
>>> dm4 = DecayMode(0.98823, "gamma gamma") # pi0
>>> dc = DecayChain("D*+", {"D*+":dm1, "D0":dm2, "K_S0":dm3, "pi0":dm4})
>>> print(dc.to_string())
D*+ -> (D0 -> (K_S0 -> pi+ pi-) (pi0 -> gamma gamma)) pi+

• Add DecFileParser.expand_decay_modes(particle) which returns single-line strings for all full decay chains of the given particle, e.g.:

>>> p = DecFileParser("tests/data/test_example_Dst.dec")
>>> p.parse()
>>> p.expand_decay_modes("D*+")
['D*+ -> (D0 -> K- pi+) pi+', 'D*+ -> (D+ -> (pi0 -> gamma gamma) K- pi+ pi+) (pi0 -> gamma gamma)', 'D*+ -> (D+ -> (pi0 -> gamma gamma) K- pi+ pi+) (pi0 -> e+ e- gamma)', 'D*+ -> (D+ -> (pi0 -> gamma gamma) K- pi+ pi+) (pi0 -> e+ e+ e- e-)', 'D*+ -> (D+ -> (pi0 -> gamma gamma) K- pi+ pi+) (pi0 -> e+ e-)', 'D*+ -> (D+ -> (pi0 -> e+ e- gamma) K- pi+ pi+) (pi0 -> gamma gamma)', 'D*+ -> (D+ -> (pi0 -> e+ e- gamma) K- pi+ pi+) (pi0 -> e+ e- gamma)', 'D*+ -> (D+ -> (pi0 -> e+ e- gamma) K- pi+ pi+) (pi0 -> e+ e+ e- e-)', 'D*+ -> (D+ -> (pi0 -> e+ e- gamma) K- pi+ pi+) (pi0 -> e+ e-)', 'D*+ -> (D+ -> (pi0 -> e+ e+ e- e-) K- pi+ pi+) (pi0 -> gamma gamma)', 'D*+ -> (D+ -> (pi0 -> e+ e+ e- e-) K- pi+ pi+) (pi0 -> e+ e- gamma)', 'D*+ -> (D+ -> (pi0 -> e+ e+ e- e-) K- pi+ pi+) (pi0 -> e+ e+ e- e-)', 'D*+ -> (D+ -> (pi0 -> e+ e+ e- e-) K- pi+ pi+) (pi0 -> e+ e-)', 'D*+ -> (D+ -> (pi0 -> e+ e-) K- pi+ pi+) (pi0 -> gamma gamma)', 'D*+ -> (D+ -> (pi0 -> e+ e-) K- pi+ pi+) (pi0 -> e+ e- gamma)', 'D*+ -> (D+ -> (pi0 -> e+ e-) K- pi+ pi+) (pi0 -> e+ e+ e- e-)', 'D*+ -> (D+ -> (pi0 -> e+ e-) K- pi+ pi+) (pi0 -> e+ e-)', 'D*+ -> (D+ -> (pi0 -> gamma gamma) K- pi+ pi+) gamma', 'D*+ -> (D+ -> (pi0 -> e+ e- gamma) K- pi+ pi+) gamma', 'D*+ -> (D+ -> (pi0 -> e+ e+ e- e-) K- pi+ pi+) gamma', 'D*+ -> (D+ -> (pi0 -> e+ e-) K- pi+ pi+) gamma']

• NB: this implicitly reverts aliases back to the original (EvtGen) names

Tests

• New pytest file tests/decay/test_descriptor.py which checks the functionality of DecayChain.to_string()
• Add new test test_expand_decay_chains to tests/dec/test_dec.py which tests DecFileParser.expand_decay_modes() using tests/data/test_example_Dst.dec

Other changes:

• Rename the "typedef" DecayModeDict as DecayChainDict and use in more places within decay.py
  • DecayModeDict = dict[str, Union[float, str, list[Any]]] was more suited to the "inner" dict that contained the keys "bf", "fs" etc...
  • DecayChainDict is now defined as dict[str, list[DecayModeDict]]
  • Since DecayModeDict was only internal to decay.py I think this is fine, although it could possibly break anything outside this package that might use it (can't imagine what or why)
• Replace instances in decay.py of typing.Dict and typing.List with builtin dict and list

[eduardo-rodrigues]

Thanks very much for this @admorris. Let me add some quick/trivial comments ...

[eduardo-rodrigues]

Hey @admorris, I fixed a trivial comment from MyPy but there are more pre-commit issues. Let me know if you need help and/or the timescale from your side to finalise matters. Thanks.

[eduardo-rodrigues]

Your comment "NB: this implicitly reverts aliases back to the original (EvtGen) names" above seems relevant to have in the related docstring. Once you deal with these 2 things I reckon we can move towards a final test + merging.

[admorris]

I have pushed commits that address your comments. I think it's ready to merge

[eduardo-rodrigues]

I see the CI fails because of some of the type hints you added/adapted. Did you look further into this and/or need help?

[eduardo-rodrigues]

I think you need to use Dict in both DecayModeDict and DecayChainDict type hint defs, though I do not fully understand why, to sort out the remaining issues. Can you give this a try?

[admorris]

The python 3.7 and 3.8 checks are failing also on files not touched by this PR:

 =========================== short test summary info ============================
ERROR tests/test_convert.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_convert.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_dec_full.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_dec_full.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_decaylanguage.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_decaylanguage.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_goofit.py - TypeError: 'type' object is not subscriptable
ERROR tests/test_goofit.py - TypeError: 'type' object is not subscriptable
ERROR tests/dec/test_dec.py - TypeError: 'type' object is not subscriptable
ERROR tests/dec/test_dec.py - TypeError: 'type' object is not subscriptable
ERROR tests/dec/test_issues.py - TypeError: 'type' object is not subscriptable
ERROR tests/dec/test_issues.py - TypeError: 'type' object is not subscriptable
ERROR tests/decay/test_decay.py - TypeError: 'type' object is not subscriptable
ERROR tests/decay/test_decay.py - TypeError: 'type' object is not subscriptable
ERROR tests/decay/test_descriptor.py - TypeError: 'type' object is not subscriptable
ERROR tests/decay/test_descriptor.py - TypeError: 'type' object is not subscriptable
ERROR tests/decay/test_viewer.py - TypeError: 'type' object is not subscriptable
ERROR tests/decay/test_viewer.py - TypeError: 'type' object is not subscriptable
ERROR tests/utils/test_utilities.py - TypeError: 'type' object is not subscriptable
ERROR tests/utils/test_utilities.py - TypeError: 'type' object is not subscriptable
!!!!!!!!!!!!!!!!!!! Interrupted: 20 errors during collection !!!!!!!!!!!!!!!!!!!
============================== 20 errors in 5.57s ==============================

[eduardo-rodrigues]

Yup, because the touched files are imported all over ;-).

[eduardo-rodrigues]

You're almost there ...

[eduardo-rodrigues]

Super 👍! I'm going to merge and likely make a release soon. There are plenty of tests to add for added functionality, but that can be a follow-up (in fact I already started collecting some files from LHCb that contained the new keywords and models).

Thank you.