Metadata-Version: 2.1
Name: numpythia
Version: 1.2.0
Summary: The interface between PYTHIA and NumPy
Home-page: http://github.com/scikit-hep/numpythia
Maintainer: the Scikit-HEP admins
Maintainer-email: scikit-hep-admins@googlegroups.com
License: GPLv3
Platform: UNKNOWN
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
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: Programming Language :: C++
Classifier: Programming Language :: Cython
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*
Requires-Dist: numpy
Requires-Dist: six
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'

.. -*- mode: rst -*-

numpythia: The interface between PYTHIA and NumPy
=================================================

.. image:: https://img.shields.io/pypi/v/numpythia.svg
   :target: https://pypi.python.org/pypi/numpythia

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1471492.svg
  :target: https://doi.org/10.5281/zenodo.1471492

.. image:: https://github.com/scikit-hep/numpythia/workflows/Main/badge.svg?branch=master
   :target: https://github.com/scikit-hep/numpythia/actions
   :alt: Test status

.. image:: https://dev.azure.com/scikit-hep/numpythia/_apis/build/status/scikit-hep.pyjet?branchName=master
   :target: https://dev.azure.com/scikit-hep/numpythia/_build/latest?definitionId=9&branchName=master
   :alt: Wheel builds

numpythia provides an interface between `PYTHIA
<http://home.thep.lu.se/Pythia/>`_ and `NumPy
<http://www.numpy.org/>`_ allowing you to generate events as NumPy arrays of
particle four-momenta. By default numpythia only depends on NumPy and builds
internal copies of the PYTHIA and `HepMC <http://hepmc.web.cern.ch/hepmc/>`_
source code.

Standalone Installation
-----------------------

To simply use the built-in PYTHIA and HepMC::

   pip install -v numpythia

And you're good to go!

Support for building against an external PYTHIA is on the wishlist.

Note that if you are using a Mac OSX system, then installation may require setting an
environment variable as `explained here <https://github.com/pytorch/pytorch/issues/1434>`_.

Strict dependencies
-------------------

- `Python <http://docs.python-guide.org/en/latest/starting/installation/>`__ (2.7+, 3.4+)
- `Numpy <https://scipy.org/install.html>`__
- `six <https://six.readthedocs.io/>`__
- Source builds: `Cython <https://cython.org/>`__ and a compiler.

Getting started
---------------

.. code-block:: python

   >>> from numpythia import Pythia, hepmc_write, hepmc_read
   >>> from numpythia import STATUS, HAS_END_VERTEX, ABS_PDG_ID
   >>> from numpythia.testcmnd import get_cmnd
   >>> from numpy.testing import assert_array_equal

   >>> pythia = Pythia(get_cmnd('w'), random_state=1)

   >>> selection = ((STATUS == 1) & ~HAS_END_VERTEX &
               (ABS_PDG_ID != 12) & (ABS_PDG_ID != 14) & (ABS_PDG_ID != 16))

   >>> # generate events while writing to ascii hepmc
   >>> for event in hepmc_write('events.hepmc', pythia(events=1)):
   >>>    array1 = event.all(selection)

   >>> # read the same event back from ascii hepmc
   >>> for event in hepmc_read('events.hepmc'):
   >>>    array2 = event.all(selection)

   >>> assert_array_equal(array1, array2)
   True

The dtype of any array of particle information is:

.. code-block:: python

   np.dtype([('E', 'f8'), ('px', 'f8'), ('py', 'f8'), ('pz', 'f8'), ('pt', 'f8'),
             ('mass', 'f8'), ('rap', 'f8'), ('eta', 'f8'), ('theta', 'f8'),
             ('phi', 'f8'), ('prodx', 'f8'), ('prody', 'f8'), ('prodz', 'f8'),
             ('prodt', 'f8'), ('pdgid', 'i4'), ('status', 'i4')])

Also see `pyjet <https://github.com/scikit-hep/pyjet>`_ for jet clustering.

Tutorial
--------

Setting PYTHIA
~~~~~~~~~~~~~~

PYTHIA settings can be passed in one of three ways: through the `**kwargs` arguments of the constructor `Pythia(..., **kwargs)`:

.. code-block:: python

   >>> pythia = Pythia(..., Beams_eCM=13000.)

Or as a dictionary:

.. code-block:: python

   >>> pythia = Pythia(..., params={'Beams:eCM':  13000.})

Or via a Python command file:

.. code-block:: python

   >>> pythia = Pythia(config='path/to/config.cmd')

The full list of settings can be found on the  `PYTHIA homepage <http://home.thep.lu.se/Pythia/>`_.

Note that the ":" in settings names is replaced by a "_"  if using `kwargs`.
`kwargs` take precedence over `params` and they both take precedence over `config`.
Example config files can be found under the `numpythia.testcmnd` directory.

Generate events
~~~~~~~~~~~~~~~

To generate events do

.. code-block:: python

   >>> events = pythia(events=100)
   >>> events
   <generator at 0x10cf06f78>

where **events** is a generator of ``GenEvent`` containing all the generated particles.

Generated particles can be accessed through the ``all``, ``first`` and ``last``
methods which have two optional arguments ``selection`` and ``return_hepmc``.
Selection is a filter or a combination of filters with bitwise operations (as
shown in the *getting started* example) applied on the particles in the event.
The available filters are

.. code-block:: python

    STATUS, PDG_ID, ABS_PDG_ID, HAS_END_VERTEX, HAS_PRODUCTION_VERTEX,
    HAS_SAME_PDG_ID_DAUGHTER, IS_STABLE, IS_BEAM

``return_hepmc`` is by default set to ``False`` when using ``all``:

.. code-block:: python

   >>> for e in events:
   >>>     array = e.all(selection)

returns an array of particles, with the dtype described above. ``return_hepmc`` is
by default set to ``True`` for ``first`` and ``last``:

.. code-block:: python

    >>> for e in events:
    >>>     gen_part_f = e.first(selection)
    >>>     gen_part_l = e.last(selection)

returns a ``GenParticle``.

Generated particle
~~~~~~~~~~~~~~~~~~

``GenParticle`` is the numpythia interface of
`HepMC::GenParticle <http://lcgapp.cern.ch/project/simu/HepMC/205/html/classHepMC_1_1GenParticle.html>`_,
and has the following attributes

.. code-block:: python

    pid, status, e, px, py, pz, pt, eta, phi, mass, theta, rap

``GenParticle`` also has the following methods ``parents``, ``children``, ``ancestors``,
``descendants`` and ``siblings`` both with the two optional arguments ``selection``
and ``return_hepmc`` described before. For instance:

.. code-block:: python

    >>> for e in events:
    >>>     w = e.last((ABS_PDG_ID == 24) & HAS_END_VERTEX))
    >>>     w.children()
    array([(240.60708981, 115.76101664, 126.16766767, -169.03439984, 171.22760682, 0.5, -0.87228439, -0.87228739, 2.34974894, 0.82838703, 0., 0., 0., 0.,  3, 23),
       ( 52.59241372,   9.21296404,  50.77873929,  -10.01763001,  51.60774235, 1.5, -0.19283178, -0.19291222, 1.76252302, 1.39131523, 0., 0., 0., 0., -4, 23)],
      dtype=[('E', '<f8'), ('px', '<f8'), ('py', '<f8'), ('pz', '<f8'), ('pT', '<f8'), ('mass', '<f8'), ('rap', '<f8'), ('eta', '<f8'), ('theta', '<f8'), ('phi', '<f8'), ('prodx', '<f8'), ('prody', '<f8'), ('prodz', '<f8'), ('prodt', '<f8'), ('pdgid', '<i4'), ('status', '<i4')])


