{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# pyhepmc: a Pythonic interface to HepMC3\n",
    "\n",
    "**Hans Dembinski** | TU Dortmund\n",
    "\n",
    "**PyPI** https://pypi.org/project/pyhepmc\n",
    "\n",
    "**Source** https://github.com/scikit-hep/pyhepmc\n",
    "\n",
    "**Documentation** https://scikit-hep.org/pyhepmc\n",
    "\n",
    "**Latest release** v2.7.1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## HepMC3 C++ library\n",
    "\n",
    "* [HepMC3](http://hepmc.web.cern.ch/hepmc/), [A. Buckley and others, Comput.Phys.Commun. 260 (2021) 107310](https://linkinghub.elsevier.com/retrieve/pii/S0010465520301181)\n",
    "* C++ library and ASCII format to store simulated event records\n",
    "* Object oriented: event, particle, vertex are classes\n",
    "* Store metadata about run, event, particle, vertex"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Typical workflow\n",
    "\n",
    "Generator (Pythia, ...) $\\longrightarrow$ HepMC3 file $\\longrightarrow$ detector simulation, Rivet, ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### pyhepmc is a hand-crafted Python interface\n",
    "\n",
    "* Based on [pybind11](https://pybind11.readthedocs.io/en/stable/index.html)\n",
    "* Previously known as *pyhepmc-ng*\n",
    "* Was proposed for inclusion in HepMC3\n",
    "* HepMC3 authors preferred automatically generated Python interface with [cppbinder](https://cppbinder.readthedocs.io/en/latest/about.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Advantages of pyhepmc\n",
    "\n",
    "### Easy installation\n",
    "\n",
    "* `pip install pyhepmc`\n",
    "* Precompiled wheels for all common platforms\n",
    "* HepMC3 library included: start working immediately"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Pythonic API\n",
    "* Properties instead of C++ setters/getters\n",
    "* Implicit conversions between native Python types and native C++ types\n",
    "* Simple IO with `pyhepmc.open`\n",
    "* Flexible import from legacy HEPEVT record (Pythia 6, ...), used by [impy generator frontend](https://github.com/impy-project/impy)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Event visualization in Jupyter notebooks\n",
    "\n",
    "* Based on [graphviz](https://graphviz.org/)\n",
    "* Extra info from [particle](https://github.com/scikit-hep/particle) in SVG tooltips\n",
    "\n",
    "![](https://github.com/scikit-hep/pyhepmc/raw/main/docs/_static/pyhepmc.svg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Simple IO"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "import pyhepmc\n",
    "\n",
    "with pyhepmc.open(\"sibyll21.dat\") as f:\n",
    "    for event in f:\n",
    "        ... # do something with event"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(0.21799583733081818, -211, 'pi-'),\n",
       " (0.2832586169242859, 211, 'pi+'),\n",
       " (0.2986985743045807, -211, 'pi-'),\n",
       " (0.3166664242744446, -211, 'pi-'),\n",
       " (0.3245152235031128, 22, 'gamma'),\n",
       " (0.3567061126232147, 211, 'pi+'),\n",
       " (0.5115386843681335, 22, 'gamma'),\n",
       " (0.5509395003318787, 22, 'gamma'),\n",
       " (0.5818261504173279, 22, 'gamma'),\n",
       " (0.876023530960083, 211, 'pi+'),\n",
       " (1.4933778047561646, 22, 'gamma'),\n",
       " (1.5073537826538086, 2212, 'p'),\n",
       " (1.5396702289581299, 22, 'gamma'),\n",
       " (1.607804298400879, 22, 'gamma'),\n",
       " (1.9595634937286377, 22, 'gamma'),\n",
       " (7.576014518737793, 2212, 'p')]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from particle import Particle  # great synergies\n",
    "\n",
    "# energy, PDG ID, name of final-state particles in the record (sorted)\n",
    "def en(p): return p.momentum.e\n",
    "def name(p): return Particle.from_pdgid(p.pid).name\n",
    "\n",
    "sorted([(en(p), p.pid, name(p)) for p in event.particles if p.status == 1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Attributes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "GenRunInfo(tools=[ToolInfo(name='SIBYLL', version='2.1', description='')], weight_names=[], attributes={})"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "event.run_info"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "# mark all vertices with photon children as \"sparkly\"\n",
    "for v in event.vertices:\n",
    "    if any(q.pid == 22 for q in v.particles_out):\n",
    "        v.attributes[\"sparkly\"] = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Transparent (de)compression\n",
    "\n",
    "* Using Python's stdlib\n",
    "* No external libraries needed\n",
    "* gzip, bzip2, lmza (xz format)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "-"
    }
   },
   "outputs": [],
   "source": [
    "with pyhepmc.open(\"output.xz\", \"w\") as f:  # or .gz or .bz2\n",
    "    f.write(event)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Summary\n",
    "\n",
    "* pyhepmc is a Pythonic interface to HepMC3 C++ library\n",
    "* IO formats: HepMC2, HepMC3, HEPEVT, LHE (read-only)\n",
    "* Full documentation with Python docstrings, [online documentation is based on docstrings](https://scikit-hep.org/pyhepmc/reference.html)\n",
    "* Event visualization in Jupyter\n",
    "* Nearly 100 % of C++ API covered, [only minor parts missing](https://scikit-hep.org/pyhepmc/reference.html#differences-between-hepmc3-c-and-pyhepmc)\n",
    "* 100 % API coverage with unit tests"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.13"
  },
  "vscode": {
   "interpreter": {
    "hash": "1ee38ef4a5a9feb55287fd749643f13d043cb0a7addaab2a9c224cbe137c0062"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}