Add example with pt, eta, phi, M four-vector

[matthewfeickert]

Hi. In the Array Oriented Interface docs there is an example of how to make an Awkward Array that is a Record Array of Lorentz Vectors

fastjet/docs/Awkward.rst

Lines 35 to 48 in 5cdd16f

	The Data
	---------
	The input data for the Multi-event interface has to be an Awkward Array. One such example is as follows: ::
	>>> import awkward as ak
	>>> array = ak.Array(
	... [
	... {"px": 1.2, "py": 3.2, "pz": 5.4, "E": 2.5, "ex": 0.78},
	... {"px": 32.2, "py": 64.21, "pz": 543.34, "E": 24.12, "ex": 0.35},
	... {"px": 32.45, "py": 63.21, "pz": 543.14, "E": 24.56, "ex": 0.0},
	... ],
	... )
	The Awkward Array here is a Record Array of Lorentz Vectors.

which notes that

fastjet/docs/Awkward.rst

Lines 50 to 51 in 5cdd16f

	.. note::
	The inputs can be provided in more Awkward Array formats than described here.

It appears from the tests that the way to do this is like

fastjet/tests/test_003-vector.py

Lines 10 to 19 in 5cdd16f

	def test_vector_single():
	array = ak.Array(
	[
	{"phi": 1.2, "eta": 3.2, "rho": 5.4, "E": 2.5, "ex": 0.78},
	{"phi": 32.2, "eta": 64.21, "rho": 543.34, "E": 24.12, "ex": 0.35},
	{"phi": 32.45, "eta": 63.21, "rho": 543.14, "E": 24.56, "ex": 0.0},
	],
	with_name="Momentum4D",
	behavior=vector.backends.awkward.behavior,
	)

So the original example from the v3.4.0.5 docs

import awkward as ak
import fastjet

jetdef = fastjet.JetDefinition(fastjet.kt_algorithm, 0.6)

array = ak.Array(
    [
        {"px": 1.2, "py": 3.2, "pz": 5.4, "E": 2.5, "ex": 0.78},
        {"px": 32.2, "py": 64.21, "pz": 543.34, "E": 24.12, "ex": 0.35},
        {"px": 32.45, "py": 63.21, "pz": 543.14, "E": 24.56, "ex": 0.0},
    ],
)

cluster = fastjet.ClusterSequence(array, jetdef)
inclusive_jets = cluster.inclusive_jets()
print(inclusive_jets)

$ python example.py 
#--------------------------------------------------------------------------
#                         FastJet release 3.4.0
#                 M. Cacciari, G.P. Salam and G. Soyez                  
#     A software package for jet finding and analysis at colliders      
#                           http://fastjet.fr                           
#	                                                                      
# Please cite EPJC72(2012)1896 [arXiv:1111.6097] if you use this package
# for scientific work and optionally PLB641(2006)57 [hep-ph/0512210].   
#                                                                       
# FastJet is provided without warranty under the GNU GPL v2 or higher.  
# It uses T. Chan's closest pair algorithm, S. Fortune's Voronoi code,
# CGAL and 3rd party plugin jet algorithms. See COPYING file for details.
#--------------------------------------------------------------------------
[{px: 64.7, py: 127, pz: 1.09e+03, E: 48.7}, {px: 1.2, py: 3.2, ...}]

would be revised to something like

import awkward as ak
import fastjet
import vector

jetdef = fastjet.JetDefinition(fastjet.kt_algorithm, 0.6)

# Nonsense numbers
# c.f. https://github.com/scikit-hep/fastjet/blob/5cdd16f7dda5b52949f244501504b0906cdc0689/tests/test_003-vector.py#L10-L19
array = ak.Array(
    [
        {"pt": 1.1, "eta": 2.1, "phi": 3.1, "M": 4.1, "ex": 0.78},
        {"pt": 1.2, "eta": 2.2, "phi": 3.2, "M": 4.2, "ex": 0.35},
        {"pt": 1.3, "eta": 2.3, "phi": 3.3, "M": 4.3, "ex": 0.0},
    ],
    with_name="Momentum4D",
    behavior=vector.backends.awkward.behavior,
)

cluster = fastjet.ClusterSequence(array, jetdef)
inclusive_jets = cluster.inclusive_jets()
print(inclusive_jets)

$ python example.py 
#--------------------------------------------------------------------------
#                         FastJet release 3.4.0
#                 M. Cacciari, G.P. Salam and G. Soyez                  
#     A software package for jet finding and analysis at colliders      
#                           http://fastjet.fr                           
#	                                                                      
# Please cite EPJC72(2012)1896 [arXiv:1111.6097] if you use this package
# for scientific work and optionally PLB641(2006)57 [hep-ph/0512210].   
#                                                                       
# FastJet is provided without warranty under the GNU GPL v2 or higher.  
# It uses T. Chan's closest pair algorithm, S. Fortune's Voronoi code,
# CGAL and 3rd party plugin jet algorithms. See COPYING file for details.
#--------------------------------------------------------------------------
[{px: -3.58, py: -0.229, pz: 16.2, E: 20.9}]

If this is the best way to do this sort of thing, can an example be added to the docs to demonstrate this as this is an exceptionally common basis to use?

[charlie-norgaard]

Hi, I was wondering if there was any update on this? I'm trying to do something very similar on my end. Any help would be greatly appreciated!

[matthewfeickert]

Hi, I was wondering if there was any update on this? I'm trying to do something very similar on my end.

@charlie-norgaard What are you looking for in terms of an update? An update in my mind would be a PR that extends the documentation and closes this Issue.

If you have a particular problem that you're trying to solve please post a reproducible minimal example that demonstrates your issue.

[matthewfeickert]

Thanks for taking care of this @chrispap95!