用于描述、操作和转换粒子衰变的语言
项目描述
DecayLanguage: 描述、操作和转换粒子衰变
DecayLanguage实现了一种语言，用于描述和转换粒子衰变，在数字表示之间进行转换，从而使得多个拟合程序之间能够互操作。特别关注的是专门用于振幅分析程序。
DecayLanguage 提供了解析所谓的 .dec 衰变文件的工具，并可以描述、操作和可视化衰变链。
安装
只需运行以下命令
pip install decaylanguage
您可以使用 pipenv 或通过 --user 选项创建虚拟环境，如果您了解这些内容的话。支持 Python 3.8+（《0.12》版本支持 Python 2 和 3.5，0.14 版本支持 Python 3.6，0.18 版本支持 Python 3.7）。
依赖项：（点击展开）
所需的和兼容性依赖项将由 pip 自动安装。
所需依赖项
- particle：PDG 粒子数据和识别代码
- NumPy：Python 的数值库
- pandas：Python 中的表格数据
- attrs：Python 的数据类
- plumbum：命令行工具
- lark：Python 的现代解析库
- graphviz 以渲染（DOT 语言）衰变链的描述和可视化。
Python 兼容性
- 如果使用 Python /< 3.9，则可以使用 importlib_resources 进行回滚
入门
使用 Binder 示例 是开始使用 DecayLanguage 的绝佳方式。
这是一份快速用户指南。要获取完整的 API 文档，请点击此处（请注意，目前仍在开发中）。
什么是 DecayLanguage？
DecayLanguage 是一组用于构建和转换粒子衰变的工具
-
它提供了解析所谓的
.dec衰变文件的工具，并可以描述、操作和可视化生成的衰变链。 -
它实现了一种语言，用于描述和转换粒子衰变之间的数字表示，从而使得多个拟合程序之间能够互操作。特别关注的是专门用于振幅分析的程序。
粒子
粒子是在处理衰变时的关键组件。有关如何处理粒子和蒙特卡洛粒子识别代码的信息，请参阅 particle 包。
解析衰变文件
可以使用以下方式简单解析衰变 .dec 文件
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. ...
为了方便起见，提供了 LHCb 实验使用的 DECAY.DEC 主文件的副本，链接如下 这里。
DecFileParser 类实现了一系列方法，可以访问存储在衰变文件中的所有信息：衰变本身、粒子名称别名、电荷共轭粒子的定义、变量和 Pythia 特定的定义等。
从多行字符串而不是文件中解析可能很方便
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()
高级用法
可以通过以下方式检查包所知的 .dec 文件衰变模型列表
from decaylanguage.dec import known_decay_models
假设您必须处理一个包含上述列表中尚未列出的新模型的衰变文件。按常规运行解析器将在模型解析时产生错误。尽管如此，处理这个问题很容易；无需等待新版本的发布：只需在解析文件之前，使用您想要添加的模型作为参数调用 load_additional_decay_models 即可。
dfp = DecFileParser('my_decfile.dec')
dfp.load_additional_decay_models("MyModel1", "MyModel2")
dfp.parse()
...
话虽如此，如果您发现缺失了模型，请提交拉取请求以添加新模型...
可视化衰变文件
DecayChainViewer 类允许可视化解析的衰变链
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
实际的图形如下所示
# ...
dcv = DecayChainViewer(d)
dcv.graph
这使得所有 graphviz.Digraph 类属性和方法都可用，例如
dcv.graph.render(filename='mygraph', format='pdf', view=True, cleanup=True)
同样，在实例化 DecayChainViewer 时，所有 graphviz.Digraph 类属性都可以设置
dcv = DecayChainViewer(chain, name='TEST', format='pdf')
衰变链的通用表示
已经设计了一系列类和方法，以提供任何复杂程度的粒子衰变链的通用表示，并提供在这些表示之间转换的能力。具体来说，实现了基于类和字典的表示。
以下是一个衰变链的类表示示例
>>> 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>
可以使用 DecayChainViewer 类和字典表示 dc.to_dict() 来可视化衰变链，这是 DecayChainViewer 理解的简单表示，如上所述
DecayChainViewer(dc.to_dict())
提供两种粒子衰变链表示的事实确保了以下内容
- 可读性高（类）且效率高（字典）的替代方案。
- 对衰变链信息的解析、操作和存储的灵活性。
衰变建模
创建衰变链最常见的方式是从文件或字符串中读取 AmpGen 风格语法。你可以使用
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
''')
在这里，lines 将是一个振幅链行列表（在 Jupyter 笔记本中支持美化打印），parameters 将是参数表（目前不支持范围参数），constants 将是常数表，而 states 将是已知状态的列表（EventType）。
转换器
你可以输出到一种格式（目前仅支持 GooFit，欢迎提交 PR 以添加更多）。使用 DecayChain 的子类，在这种情况下，GooFitChain。要使用 GooFit 输出，请在 shell 中键入
python -m decaylanguage -G goofit myinput.opts
贡献者
我们在此感谢使本项目成为可能的贡献者（emoji key）
 Eduardo Rodrigues 🚧 💻 📖 |
 Henry Schreiner 🚧 💻 📖 |
 Yipeng Sun 💻 |
 Chris Burr 📖 |
 Kilian Lieret 📖 |
 Moritz Bauer 💻 |
 FlorianReiss 💻 📖 |
 Adam Morris 💻 |
 Dazhi Wang 💻 |
 Manuel Franco Sevilla 💻 |
本项目遵循 all-contributors 规范。
致谢
英国科学与技术设施理事会（STFC）和利物浦大学为 Eduardo Rodrigues（2020-）提供资金，使他能够兼职从事本项目。
2016-2019 年，本项目得到了国家科学基金会合作协议 OAC-1450377（DIANA/HEP）的支持，自 2019 年以来，该项目得到了 OAC-1836650（IRIS-HEP）的支持。本文档中表达的意见、发现、结论或建议均为作者的观点，不一定反映国家科学基金会的观点。
下载文件
下载适用于您平台的文件。如果您不确定该选择哪个，请了解有关安装包的更多信息。
