add LHCb submodule with conversion to/from LHCb naming scheme (#357)

* separate LHCb module

* remove class, instead have functions in lhcb.utils

* add LHCbName2PDGIDBiMap to __all__ in particle.lhcb

* add script to generate PDGID/LHCb name conversion table from DDDB

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* copyright statement and docstring in dump_pdgid_to_lhcb.py

* Update MANIFEST.in to exclude admin folder

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eduardo Rodrigues <eduardo.rodrigues@cern.ch>

MANIFEST.in

@@ -11,6 +11,7 @@ global-exclude __pycache__
 prune docs
 prune notebooks
 prune tests
+prune admin
 prune .ci
 prune .github
 exclude .pre-commit-config.yaml environment.yml codecov.yml

admin/dump_pdgid_to_lhcb.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# 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/particle for details.
+"""This script generates the PDGID<->LHCb name mapping using the table from the LHCb DDDB package."""
+
+import csv
+import datetime as dt
+
+import requests
+
+
+def download_table(
+    url="https://gitlab.cern.ch/lhcb-conddb/DDDB/-/raw/master/param/ParticleTable.txt",
+):
+    r = requests.get(url)
+    r.raise_for_status()
+
+    lines = r.text.split("\n")
+
+    return [line.split() for line in filter(lambda x: x and x[0] == " ", lines)]
+
+
+def main():
+    date = dt.datetime.today().strftime("%Y-%m-%d")
+    table = download_table()
+    lhcb_names = {int(pdg_id): name for name, _, pdg_id, *_ in table}
+
+    with open("src/particle/lhcb/data/pdgid_to_lhcbname.csv", "w") as out_csv:
+        out_csv.write(
+            f"# (c) Scikit-HEP project - Particle package data file - pdgid_to_lhcbname.csv - {date}\n"
+        )
+        writer = csv.DictWriter(
+            out_csv, fieldnames=("PDGID", "STR"), lineterminator="\n"
+        )
+        writer.writeheader()
+
+        for pid, name in sorted(
+            lhcb_names.items(), key=lambda x: (abs(int(x[0])), -int(x[0]))
+        ):
+            writer.writerow({"PDGID": pid, "STR": name})
+
+
+if __name__ == "__main__":
+    main()

src/particle/lhcb/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+# 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/particle for details.
+
+from __future__ import absolute_import
+
+from typing import Tuple
+
+from .converters import LHCbName2PDGIDBiMap
+from .utils import from_lhcb_name, to_lhcb_name
+
+__all__ = (
+    "from_lhcb_name",
+    "to_lhcb_name",
+    "LHCbName2PDGIDBiMap",
+)
+
+
+def __dir__():
+    # type: () -> Tuple[str, ...]
+    return __all__

src/particle/lhcb/converters/__init__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+# 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/particle for details.
+
+from __future__ import absolute_import
+
+from typing import Tuple
+
+from .lhcb import LHCbName2PDGIDBiMap
+
+__all__ = ("LHCbName2PDGIDBiMap",)
+
+
+def __dir__():
+    # type: () -> Tuple[str, ...]
+    return __all__

src/particle/lhcb/converters/lhcb.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+# 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/particle for details.
+
+from __future__ import absolute_import
+
+from ...converters.bimap import BiMap
+from ...pdgid import PDGID
+from .. import data
+
+LHCbName2PDGIDBiMap = BiMap(
+    PDGID,
+    str,
+    converters=(int, str),
+    filename=data.basepath / "pdgid_to_lhcbname.csv",
+)
+LHCbName2PDGIDBiMap.__doc__ = """
+Bi-bidirectional map between PDG IDs and LHCb names.
+
+Examples
+--------
+>>> name = LHCbName2PDGIDBiMap[PDGID(-531)]
+>>> name
+'B_s~0'
+
+>>> pdgid = LHCbName2PDGIDBiMap['B_s~0']
+>>> pdgid
+<PDGID: -531>
+"""

src/particle/lhcb/data/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+# 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/particle for details.
+
+import sys
+
+if sys.version_info < (3, 9):
+    import importlib_resources as resources
+else:
+    import importlib.resources as resources
+
+
+basepath = resources.files(__name__)