[REVIEW]: Vector: JIT-compilable mathematical manipulations of ragged Lorentz vectors

[editorialbot]

Submitting author: @Saransh-cpp (Saransh Chopra)
Repository: https://github.com/scikit-hep/vector
Branch with paper.md (empty if default branch): paper
Version: v1.5.2
Editor: @adonath
Reviewers: @AnnikaStein, @rafaelab
Archive: Pending

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/1baf6a622a82d5ae3769726baa95fc0c"><img src="https://joss.theoj.org/papers/1baf6a622a82d5ae3769726baa95fc0c/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/1baf6a622a82d5ae3769726baa95fc0c/status.svg)](https://joss.theoj.org/papers/1baf6a622a82d5ae3769726baa95fc0c)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@AnnikaStein & @rafaelab, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review.
First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @adonath know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @AnnikaStein

📝 Checklist for @rafaelab

[editorialbot]

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.1038/s41586-020-2649-2 is OK
- 10.5281/zenodo.7733568 is OK
- 10.5281/zenodo.4341376 is OK
- 10.7717/peerj-cs.103 is OK
- 10.1016/j.nuclphysb.2023.116103 is OK
- 10.1051/epjconf/202429506016 is OK
- 10.1007/s41781-020-0035-2 is OK
- 10.5281/zenodo.7504167 is OK
- 10.5281/zenodo.1217031 is OK
- 10.5281/zenodo.3895860 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: Numba: A llvm-based python jit compiler
- No DOI given, and none found for title: Particle Transformer for Jet Tagging
- No DOI given, and none found for title: spyral-utils
- No DOI given, and none found for title: weaver-core

❌ MISSING DOIs

- 10.25080/majora-7b98e3ed-013 may be a valid DOI for title: Dask: Parallel computation with blocked algorithms...

❌ INVALID DOIs

- None

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.98  T=0.38 s (963.2 files/s, 172366.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                         236           9423           4644          39300
SVG                              2              1              1           3496
Markdown                         6            420             14           1325
Jupyter Notebook                 1              0           3669            415
YAML                            12             54             25            380
reStructuredText                99            149            640            273
TOML                             1              8              0            250
TeX                              1             14              0            189
JSON                             1              0              0             32
DOS Batch                        1              8              1             26
make                             1              4              7              9
Text                             1              0              0              4
-------------------------------------------------------------------------------
SUM:                           362          10081           9001          45699
-------------------------------------------------------------------------------

Commit count by author:

   146	pre-commit-ci[bot]
    80	Henry Schreiner
    74	Saransh Chopra
    46	dependabot[bot]
    37	Jim Pivarski
    29	Saransh
     4	eduardo-rodrigues
     3	Matthew Feickert
     3	Naman Priyadarshi
     2	Eduardo Rodrigues
     2	Florian Bruggisser
     1	Angus Hollands
     1	Benjamin Fischer
     1	Frantic Rabbit
     1	Luke Kreczko
     1	Michael Eliachevitch
     1	N!no
     1	Peter Fackeldey
     1	Raymond Ehlers
     1	Sinclert Pérez
     1	The Gitter Badger
     1	Yogendra Sharma
     1	p-mishra1

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 602

✅ The paper includes a Statement of need section

[editorialbot]

License info:

✅ License found: BSD 3-Clause "New" or "Revised" License (Valid open source OSI approved license)

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[AnnikaStein]

Review checklist for @AnnikaStein

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the https://github.com/scikit-hep/vector?
• License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@Saransh-cpp) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
  • Yes to first question. ✅
  • For second q.: here is the ack on the repo's readme: "Acknowledgements
    This library was primarily developed by Saransh Chopra, Henry Schreiner, Jim Pivarski, Eduardo Rodrigues, and Jonas Eschle." From that, the author list could be completed.✅
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1. Contribute to the software 2. Report issues or problems with the software 3. Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
  • Minor comment: For non-specialist audience: introduce Large Hadron Collider (LHC) on first usage. ✅
• A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

  • Dask: add DOI (see the recommendation by the bot). ✅

  • JAX: add reference. ✅

  • „one of the few Lorentz vector libraries providing a Pythonic interface but a compiled…“ -> which libraries are these other few that share this property with vector? -> reference them here; or did you mean all Lorentz vector libraries in general (also those that are not compiled w/ pythonic interface)? ✅

  • „LHC and other experiments“ -> the references in brackets all refer to LHC, maybe more can be found that are not LHC-related and included there; or remove the „and other experiments“ if no refs. for other experiments (could also move the other experiments part down to the list of user-facing frameworks, where non-LHC is indeed present) ✅

[Saransh-cpp]

@editorialbot generate pdf

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[Saransh-cpp]

@editorialbot check references

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

✅ OK DOIs

- 10.1038/s41586-020-2649-2 is OK
- 10.5281/zenodo.7733568 is OK
- 10.5281/zenodo.4341376 is OK
- 10.25080/Majora-7b98e3ed-013 is OK
- 10.7717/peerj-cs.103 is OK
- 10.1016/j.nuclphysb.2023.116103 is OK
- 10.1051/epjconf/202429506016 is OK
- 10.1007/s41781-020-0035-2 is OK
- 10.5281/zenodo.7504167 is OK
- 10.5281/zenodo.1217031 is OK
- 10.5281/zenodo.3895860 is OK
- 10.1145/3620665.3640366 is OK
- 10.22323/1.414.0235 is OK
- 10.23731/CYRM-2020-0010 is OK

🟡 SKIP DOIs

- No DOI given, and none found for title: Numba: A llvm-based python jit compiler
- No DOI given, and none found for title: Particle Transformer for Jet Tagging
- No DOI given, and none found for title: spyral-utils
- No DOI given, and none found for title: weaver-core
- No DOI given, and none found for title: JAX: composable transformations of Python+NumPy pr...
- No DOI given, and none found for title: HEPvector: NumPy based vectors for general purpose...
- No DOI given, and none found for title: LorentzVectorHEP.jl: x, y, z, t and pt, eta, phi, ...

❌ MISSING DOIs

- None

❌ INVALID DOIs

- None

[Saransh-cpp]

@editorialbot check repository

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.98  T=0.36 s (772.0 files/s, 167116.1 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Python                         236           9550           4763          39754
Markdown                        17            257              6            708
SVG                              2              1              1            406
TeX                              1             20              0            393
YAML                            12             53             25            378
Jupyter Notebook                 5              0           3243            270
TOML                             1              8              0            252
JSON                             1              0              0             32
DOS Batch                        1              8              1             26
make                             1              4              7              9
Text                             1              0              0              4
-------------------------------------------------------------------------------
SUM:                           278           9901           8046          42232
-------------------------------------------------------------------------------

Commit count by author:

   164	pre-commit-ci[bot]
    85	Saransh Chopra
    80	Henry Schreiner
    53	dependabot[bot]
    38	Jim Pivarski
    29	Saransh
     4	Peter Fackeldey
     4	eduardo-rodrigues
     3	Aditi Juneja
     3	Matthew Feickert
     3	Naman Priyadarshi
     2	Eduardo Rodrigues
     2	Florian Bruggisser
     1	Angus Hollands
     1	Ankush Chudiwal
     1	Benjamin Fischer
     1	David Pérez-Suárez
     1	Frantic Rabbit
     1	HP (Hetav)
     1	Luke Kreczko
     1	Michael Eliachevitch
     1	N!no
     1	Raymond Ehlers
     1	Sinclert Pérez
     1	The Gitter Badger
     1	Yogendra Sharma
     1	p-mishra1

[editorialbot]

Paper file info:

📄 Wordcount for paper.md is 683

✅ The paper includes a Statement of need section

[editorialbot]

License info:

✅ License found: BSD 3-Clause "New" or "Revised" License (Valid open source OSI approved license)

[Saransh-cpp]

Hi @AnnikaStein, thank you for the review! I have updated the draft to address your comments. I am not sure how the process is supposed to proceed, but please let me know if the changes look good.

[AnnikaStein]

HI @Saransh-cpp
Great, I have already ticked off all my checkboxes and I am happy with the changes.
The second reviewer will also generate such checklist with their comments. From my side, it's fine.

[rafaelab]

Review checklist for @rafaelab

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the https://github.com/scikit-hep/vector?
• License: Does the repository contain a plain-text LICENSE or COPYING file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@Saransh-cpp) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1. Contribute to the software 2. Report issues or problems with the software 3. Seek support

Software paper

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[rafaelab]

@Saransh-cpp
Excellent work! I tested all provided examples and a few more applications, and everything worked just fine.
I also cross-checked your Lorentz transformations, pseudorapidities calculations, etc, just in case... They all check out.

I have only a couple of minor (non-technical) comments. The first two are necessary for me to finish the checklist, the other is just out of curiosity.

• The documentation should necessarily specify things like metric conventions for four-vectors (that also changes definitions of time-like and space-like). People working in general relativity tend to use the other convention (and some in HEP as well).
• It is also important to explicitly add to the documentation if boosts are active or passive.
• I'd be interested in seeing two performance benchmarks comparing to ROOT's TLorentzVector, a simple one, and one with Numba.

Wishlist:

• Allow the user to choose the metric convention (for people not in HEP, this is very useful)
• A constructor such as vector.obj(rho=1) that assumes theta=0 and phi=0 automatically would be very handy.
• Along these lines, a constructor like VectorObject3D(x=1) automatically setting y and z to 0 would be useful.

[Saransh-cpp]

Thanks for the detailed review, @rafaelab!

• The documentation should necessarily specify things like metric conventions for four-vectors (that also changes definitions of time-like and space-like). People working in general relativity tend to use the other convention (and some in HEP as well).
• It is also important to explicitly add to the documentation if boosts are active or passive.

I am hoping @henryiii or @jpivarski can help me with these (I hope it is okay to ping you both on this review).

1. If I am not wrong, Vector follows the metric conventions is (-,-,-,+). @rafaelab could you please clarify if by changing the definitions of time-like and space-like you mean updating the docstrings of is_timelike and is_spacelike to highlight this convention?
2. Given that we follow ROOT, the boosts should be active, as formalised in - https://root.cern/topical/GenVector.pdf. However, the PDF also says that the conventions for Euler angles is passive. Should we just link to the PDF to reference the active/passive conventions Vector follows?

• I'd be interested in seeing two performance benchmarks comparing to ROOT's TLorentzVector, a simple one, and one with Numba.

There was an attempt for writing benchmarks against ROOT, but the efforts stalled a few years back - scikit-hep/vector#36. I will ping the other maintainers and check if someone is interested in finishing that PR. We already have a Numba notebook, and I have created a PR to showcase simple comparisons between JIT and non-JIT calls - scikit-hep/vector#565.

• Allow the user to choose the metric convention (for people not in HEP, this is very useful)
• A constructor such as vector.obj(rho=1) that assumes theta=0 and phi=0 automatically would be very handy.
• Along these lines, a constructor like VectorObject3D(x=1) automatically setting y and z to 0 would be useful.

It would be amazing if you can open standalone issues for these bullet points in the vector repository. I (or someone else) will take a look at them as soon as possible!