Skip to content

Commit 29ad6c7

Browse files
aryan26royjpivarski
aryan26roy
and
jpivarski
authored
Added awkward tutorial (#67)
* Added awkward tutorial * Added docs for classic interface * Added readthedocs yaml * Changed paths in conf.py * changed readme * removed badge from top * removed badge from top * changed alignment * Added description * Find the right path. * Added autodoc_mock_imports. * Added single page for classic interface classes * Added awkward in requirements.txt Co-authored-by: Jim Pivarski <[email protected]>
1 parent a1d92be commit 29ad6c7

10 files changed

+200
-83
lines changed

‎.readthedocs.yml

+1-4
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,4 @@ formats: all
1515
python:
1616
version: 3.8
1717
install:
18-
- method: pip
19-
path: .
20-
extra_requirements:
21-
- docs
18+
- requirements: docs/requirements.txt

‎README.md

+10-53
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
11
<img src="docs/logo.svg">
22

33
[![Actions Status][actions-badge]][actions-link]
4-
[![Documentation Status][rtd-badge]][rtd-link]
5-
[![Code style: black][black-badge]][black-link]
6-
74
[![PyPI version][pypi-version]][pypi-link]
85
[![Conda-Forge][conda-badge]][conda-link]
9-
[![PyPI platforms][pypi-platforms]][pypi-link]
106

7+
[![PyPI platforms][pypi-platforms]][pypi-link]
118
[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
129
[![Gitter][gitter-badge]][gitter-link]
1310
[![Scikit-HEP][sk-badge]](https://scikit-hep.org/)
@@ -16,8 +13,6 @@
1613

1714
[actions-badge]: https://github.com/scikit-hep/fastjet/workflows/CI/badge.svg
1815
[actions-link]: https://github.com/scikit-hep/fastjet/actions
19-
[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
20-
[black-link]: https://github.com/psf/black
2116
[conda-badge]: https://img.shields.io/conda/vn/conda-forge/fastjet
2217
[conda-link]: https://github.com/conda-forge/fastjet-feedstock
2318
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
@@ -45,56 +40,18 @@ The package can be installed from PyPI using the following command:
4540
``` bash
4641
python -m pip install fastjet
4742
```
48-
# Overview
43+
# Tutorial
4944

50-
Some of the basic functionalities of Fastjet and how to use them are listed below.
45+
For a tutorial please look at the tutorial section of readthedocs page of this package.
5146

52-
``` python
53-
import fastjet
54-
import awkward as ak
55-
import vector
56-
```
57-
The input data can be either a awkward array or a list of Pseudojets.
58-
59-
## Awkward Array
60-
```python
61-
input_data = ak.Array(
62-
[
63-
[
64-
{"px": 1.2, "py": 3.2, "pz": 5.4, "E": 2.5, "ex": 0.78},
65-
{"px": 32.2, "py": 64.21, "pz": 543.34, "E": 24.12, "ex": 0.35},
66-
{"px": 32.45, "py": 63.21, "pz": 543.14, "E": 24.56, "ex": 0.0},
67-
],
68-
[
69-
{"px": 1.2, "py": 3.2, "pz": 5.4, "E": 2.5, "ex": 0.78},
70-
{"px": 32.2, "py": 64.21, "pz": 543.34, "E": 24.12, "ex": 0.35},
71-
{"px": 32.45, "py": 63.21, "pz": 543.14, "E": 24.56, "ex": 0.0},
72-
],
73-
],
74-
with_name="Momentum4D",
75-
)
76-
```
77-
## List of PseudoJets
78-
```Python
79-
input_data = [fastjet.PseudoJet(1,1,1,1)
80-
,fastjet.PseudoJet(1.2,1.2,1.2,1.2)
81-
,fastjet.PseudoJet(3,3,3,3)
82-
,fastjet.PseudoJet(-1,-12,2,1)
83-
,fastjet.PseudoJet(-1,-12,2.1,0.9)]
84-
```
85-
## Clustering
86-
The classes (clustering and clustering specification) are the same for all the input types:
87-
88-
```python
89-
jetdef = fastjet.JetDefinition(fastjet.antikt_algorithm, 0.6)
90-
cluster = fastjet.ClusterSequence(input_data, jetdef)
91-
```
92-
## Outputs
93-
The output can be extracted using function calls (output can be an Awkward Array or a list of PseudoJets depending on the input).
47+
<br>
48+
<p align = "center">
49+
<a href = "https://fastjet.readthedocs.io/en/latest/?">
50+
<img src = "https://readthedocs.org/projects/fastjet/badge/?" width="200" height="50">
51+
</a>
52+
</p>
53+
<br>
9454

95-
```python
96-
inclusive_jets = cluster.inclusive_jets()
97-
```
9855
# Installation For Developers
9956
Clone this repository recursively to get the dependencies.
10057

‎docs/Awkward.rst

+73
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
The Array Oriented Interface
2+
============================
3+
4+
The tutorial on this page describes how the user can use `Awkward Arrays <https://awkward-array.org/quickstart.html>`__ to perform clustering on the particle data.
5+
6+
Clustering Specification
7+
-------------------------
8+
9+
The fastjet library has some clases specifically made to provide the different parameters for clustering. This includes the following classes :
10+
11+
* `JetDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1JetDefinition.html>`__
12+
* `AreaDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1AreaDefinition.html>`__
13+
* `RangeDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1RangeDefinition.html>`__
14+
15+
For example, the JetDefinition class can be instantiated in the following way: ::
16+
17+
import fastjet
18+
jetdef = fastjet.JetDefinition(fastjet.antikt_algorithm, 0.6)
19+
20+
The JetDefinition class takes varied number of arguments, the first argument is always the type of algorithm, the number of rest of the arguments depends on how many parameters the given algorithm requires.
21+
22+
The JetAlgorithms
23+
----------------------
24+
The JetDefinition class takes `JetAlgorithms <http://fastjet.fr/repo/doxygen-3.4.0/namespacefastjet.html#a6377b557cbb936d4046d2aa936170dc0>`__ as arguments. In the above example we have chosen the Anti-kt algorithm. The list of algorithms is as following:
25+
26+
* ee_genkt_algorithm
27+
* ee_kt_algorithm
28+
* genkt_algorithm
29+
* genkt_for_passive_algorithm
30+
* kt_algorithm
31+
* cambridge_for_passive_algorithm
32+
* cambridge_algorithm
33+
* cambridge_aachen_algorithm
34+
* antikt_algorithm
35+
36+
The Data
37+
---------
38+
The input data for the Multi-event interface has to be an Awkward Array. One such example is as follows: ::
39+
40+
>>> import awkward as ak
41+
>>> array = ak.Array(
42+
... [
43+
... {"px": 1.2, "py": 3.2, "pz": 5.4, "E": 2.5, "ex": 0.78},
44+
... {"px": 32.2, "py": 64.21, "pz": 543.34, "E": 24.12, "ex": 0.35},
45+
... {"px": 32.45, "py": 63.21, "pz": 543.14, "E": 24.56, "ex": 0.0},
46+
... ],
47+
... )
48+
49+
The Awkward Array here is a Record Array of Lorentz Vectors.
50+
51+
.. note::
52+
The inputs can be provided in more Awkward Array formats than described here.
53+
54+
55+
ClusterSequence Class
56+
----------------------
57+
58+
After defining the JetDefinition class, the user can provide this instance to the ClusterSequence class as an argument, along with the input data to perform the clustering: ::
59+
60+
>>> cluster = fastjet.ClusterSequence(array, jetdef)
61+
<fastjet._pyjet.AwkwardClusterSequence object at 0x7f1413120a90>
62+
63+
64+
Extracting Information
65+
-----------------------
66+
Any output that has to be an Array will be an Awkward Array in the array oriented interface. For example: ::
67+
68+
>>> cluster.inclusive_jets()
69+
<Array [{px: 1.2, py: 3.2, ... E: 48.7}] type='2 * Momentum4D["px": float64, "py...'>
70+
71+
Limitations
72+
-----------
73+
The Awkward Array interface is only available for the fastjet.ClusterSequence class. The Awkward Array functionality is likely to be expanded to other classes in the future.

‎docs/clustersequence.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
fastjet.ClusterSequence
2-
===============
2+
=======================
3+
34
.. autoclass:: fastjet.ClusterSequence
45
:members:

‎docs/conf.py

+11-2
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,11 @@
1717
copyright = "2021, The Scikit-HEP admins"
1818
author = "Aryan Roy"
1919

20-
sys.path.insert(0, os.path.abspath("../src/fastjet"))
21-
sys.path.insert(0, os.path.abspath(".."))
20+
21+
curdir = os.path.dirname(__file__)
22+
finalpath = os.path.join(curdir, "..", "src")
23+
sys.path.insert(0, finalpath)
24+
2225
# -- General configuration ---------------------------------------------------
2326

2427
# Add any Sphinx extension module names here, as strings. They can be
@@ -30,6 +33,8 @@
3033
"sphinx.ext.napoleon",
3134
]
3235

36+
autodoc_mock_imports = ["fastjet._ext", "fastjet._pyjet", "fastjet._swig"]
37+
3338
# Add any paths that contain templates here, relative to this directory.
3439
templates_path = ["_templates"]
3540

@@ -46,6 +51,10 @@
4651
#
4752
html_theme = "sphinx_rtd_theme"
4853

54+
html_show_sourcelink = False
55+
html_logo = "../docs/logo.svg"
56+
html_theme_options = {"logo_only": True, "style_nav_header_background": "#fcfcfc"}
57+
4958
# Add any paths that contain custom static files (such as style sheets) here,
5059
# relative to this directory. They are copied after the builtin static files,
5160
# so a file named "default.css" will overwrite the builtin "default.css".

‎docs/index.rst

+27-15
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,28 @@
1-
.. |br| raw:: html
1+
.. toctree::
2+
:caption: Tutorial
3+
:hidden:
24

3-
<br/>
5+
Awkward
6+
particle
47

5-
.. role:: raw-html(raw)
6-
:format: html
8+
.. toctree::
9+
:caption: References
10+
:hidden:
711

12+
pseudojet
13+
clustersequence
14+
15+
.. |br| raw:: html
16+
17+
<br/>
818

919
.. image:: logo.svg
1020
:width: 300px
1121
:alt: fastjet
1222
:target: https://github.com/scikit-hep/fastjet
1323

14-
Fastjet is a library for perfomring Jet-Finding *within* the Scikit-HEP ecosystem.
24+
25+
Fastjet is a library for performing Jet-Finding *within* the Scikit-HEP ecosystem.
1526
The library includes the classic interface, and a new interface built to perform clustering on multi-event Awkward Array objects.
1627

1728
.. note::
@@ -21,26 +32,27 @@ Documentation
2132
---------------
2233

2334
* Python interface - This site.
24-
* `GitHub <https://github.com/scikit-hep/fastjet/>`_
35+
* `GitHub <https://github.com/scikit-hep/fastjet/>`__
2536

2637
Installation
2738
-------------
2839

29-
fastjet can be installed from `pypi <https://pypi.org/project/fastjet/>`_ using pip: ::
40+
fastjet can be installed from `pypi <https://pypi.org/project/fastjet/>`__ using pip: ::
3041

3142
pip install fastjet
3243

3344
Most users will get a precompiled binary (wheel) for your operating system and Python version. If not, the above attempts to compile from source.
3445

35-
.. toctree::
36-
:maxdepth: 2
37-
:titlesonly:
38-
:caption: Contents
39-
:glob:
46+
The Interfaces
47+
---------------
48+
The fastjet library provides many options for the user to perform clustering on HEP data. The library has been designed keeping in mind the different requirements of users.
4049

41-
pseudojet
42-
jetdefinition
43-
clustersequence
50+
The fastjet library contains two interfaces within:
51+
52+
* **The Awkward interface**
53+
* **The Classic interface**
54+
55+
The Awkward interface is the new interface made to handle multi-event data, whereas the classic interface is the same as the `C++ library <http://fastjet.fr/>`__, designed to handle the data in a particle-at-a-time fashion. The tutorials are divided into two to explain how each of the interfaces work. Please take a look at the tutorial section to get started.
4456

4557

4658

‎docs/jetdefinition.rst

-4
This file was deleted.

‎docs/particle.rst

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
The Object Oriented Interface
2+
==============================
3+
4+
Clustering the data
5+
--------------------
6+
7+
The fastjet library provides many options for the user to perform clustering on HEP data. The library has been designed keeping in mind the different requirements of users. The basic clustering process is described below.
8+
9+
10+
Clustering Specification
11+
-------------------------
12+
13+
The fastjet library has some clases specifically made to provide the different parameters for clustering. This includes the following classes :
14+
15+
* `JetDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1JetDefinition.html>`__
16+
* `AreaDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1AreaDefinition.html>`__
17+
* `RangeDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1RangeDefinition.html>`__
18+
19+
For example, the JetDefinition class can be instantiated in the following way: ::
20+
21+
import fastjet
22+
jetdef = fastjet.JetDefinition(fastjet.antikt_algorithm, 0.6)
23+
24+
The JetDefinition class takes varied number of arguments, the first argument is always the type of algorithm, the number of rest of the arguments depends on how many parameters the given algorithm requires.
25+
26+
The JetAlgorithms
27+
----------------------
28+
The JetDefinition class takes `JetAlgorithms <http://fastjet.fr/repo/doxygen-3.4.0/namespacefastjet.html#a6377b557cbb936d4046d2aa936170dc0>`__ as arguments. In the above example we have chosen the Anti-kt algorithm. The list of algorithms is as following:
29+
30+
* ee_genkt_algorithm
31+
* ee_kt_algorithm
32+
* genkt_algorithm
33+
* genkt_for_passive_algorithm
34+
* kt_algorithm
35+
* cambridge_for_passive_algorithm
36+
* cambridge_algorithm
37+
* cambridge_aachen_algorithm
38+
* antikt_algorithm
39+
40+
The Data
41+
--------
42+
43+
The input for the classic interface is a list of PseudoJets. To use the classic interface here's what the data should look like (This is a single event interface, one function call can only process one event): ::
44+
45+
>>> array = [fastjet.PseudoJet(1.1,1.2,1.3,1.4),
46+
... fastjet.PseudoJet(2.1,2.2,2.3,2.4),
47+
... fastjet.PseudoJet(3.1,3.2,3.3,3.4)]
48+
49+
50+
ClusterSequence Class
51+
----------------------
52+
53+
After defining the JetDefinition class, the user can provide this instance to the ClusterSequence class as an argument, along with the input data to perform the clustering: ::
54+
55+
fastjet.ClusterSequence(inputs, jetdef)
56+
57+
58+
Extracting Information
59+
-----------------------
60+
Any output that has to be an Array will be a list of PseudoJets if it's particle data. For example: ::
61+
62+
>>> inc_jets = cluster.inclusive_jets()
63+
>>> for elem in inc_jets:
64+
... print("px:", elem.px(),"py:", elem.py(),"pz:", elem.pz(),"E:", elem.E(),)
65+
px: 6.300000000000001 py: 6.6000000000000005 pz: 6.8999999999999995 E: 7.199999999999999

‎docs/pseudojet.rst

+9-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
1-
fastjet.PseudoJet
2-
==================
1+
The Classic Interface classes
2+
==============================
33

4-
.. autoclass:: fastjet.PseudoJet
5-
:members:
4+
The documentation for the C++ Fastjet covers all the classes in fastjet. The python classes of the classic interface behave exactly like they do in C++, therefore we are providing a link to the respective doxygen pages:
5+
6+
* `PseudoJet <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1PseudoJet.html>`__
7+
* `JetDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1JetDefinition.html>`__
8+
* `ClusterSequenceArea <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1ClusterSequence.html>`__
9+
* `AreaDefinition <http://fastjet.fr/repo/doxygen-3.4.0/classfastjet_1_1AreaDefinition.html>`__
10+
* `Every Other C++ Class (Almost all available through the classic interface) <http://fastjet.fr/repo/doxygen-3.4.0/annotated.html>`__

‎docs/requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
awkward
2+
sphinx>=2.4.4

0 commit comments

Comments
 (0)