docs: JOSS paper

[APN-Pucky]

Closes: #320

[github-actions]

🏎️ Benchmark Comparison

--------------------------------------------------------------------------------------------------- benchmark: 4 tests --------------------------------------------------------------------------------------------------
Name (time in ms)                                   Min                   Max                  Mean             StdDev                Median                IQR            Outliers     OPS            Rounds  Iterations
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_count_events_benchmark (0002_mr)          412.9398 (1.0)        425.0961 (1.0)        420.1373 (1.0)       4.4157 (1.0)        421.6557 (1.0)       8.8910 (2.40)          4;0  2.3802 (1.0)          10           1
test_count_events_benchmark (0001_base)        419.9685 (1.02)       491.2654 (1.16)       428.9546 (1.02)     21.9592 (4.97)       422.7559 (1.00)      3.6980 (1.0)           1;1  2.3312 (0.98)         10           1
test_fromfile_and_to_awkward (0002_mr)       4,045.6083 (9.80)     4,128.9367 (9.71)     4,076.7342 (9.70)     25.7760 (5.84)     4,074.4328 (9.66)     36.4396 (9.85)          2;0  0.2453 (0.10)         10           1
test_fromfile_and_to_awkward (0001_base)     4,107.3355 (9.95)     4,242.6053 (9.98)     4,168.1421 (9.92)     44.5298 (10.08)    4,158.5751 (9.86)     82.4555 (22.30)         2;0  0.2399 (0.10)         10           1
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (692c317) to head (64c3f2a).

Additional details and impacted files

@@            Coverage Diff            @@
##             paper      #337   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            2         2           
  Lines          509       509           
=========================================
  Hits           509       509           

Flag	Coverage Δ
unittests-3.10	100.00% <ø> (ø)
unittests-3.11	100.00% <ø> (ø)
unittests-3.12	100.00% <ø> (ø)
unittests-3.13	100.00% <ø> (ø)
unittests-3.14	100.00% <ø> (ø)
unittests-3.9	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[matthewfeickert]

👋 Let me know if you would like any reviews of this in advance, as I obviously won't be able to serve as the JOSS editor for this submission. :)

[matthewfeickert]

I feel like you should be first author here.

[eduardo-rodrigues]

I totally agree. I am not familiar with the format but if the list items will match to an ordered list of authors a standard way would be to have Alexander as first and then everyone else in alphabetic order by family name.

[matthewfeickert]

Indeed, that's how it ends up working in the render.

Example: https://github.com/scikit-hep/pyhf/blob/bc66d82e180f804324fcd7f40fbe9085a29f6a28/docs/JOSS/paper.md?plain=1#L10-L22 ->

[eduardo-rodrigues]

Cool, thanks.

[APN-Pucky]

Thanks, I added their action to render the PDF and upload it as an artifact. https://github.com/scikit-hep/pylhe/actions/runs/19242110752

[APN-Pucky]

I think this is my first draft you can inspect. Before going into the details I think I'd need to know if the contents are good this way or if some bigger/structural changes should be done before going into the details. I was not sure about

• too many citations?
• is it too long?
• one line of the xml is cutoff by paper width (does it change or is this the final width?)
• JOSS has no appendix (e.g. for the table)
• focus on physics (no: CI, docs, test, performance tracking)

...

The PDF can be generated locally via:

pylhe/ $ docker run --rm     --volume $PWD/paper:/data     --user $(id -u):$(id -g)     --env JOURNAL=joss     openjournals/inara

[matthewfeickert]

I haven't read the full text yet, but just taking a quick scan of the layout from the GHA generated PDF things look good (you have the "Statement of need" section, which is a hard requirement 👍) but I think you should drop anything that explains structural choices (that should go to docs) and examples (again, we would ask that those go to docs unless you need to demonstrate something explicitly about statement of need or a performance quote).

Summary and Impact sections look good and no one is going to complain about the citation count. 👍

I'll try to review the language in full by this weekend, but I also have multiple hard deadlines by Monday, so don't feel a need to wait for me if you feel confident.

[matthewfeickert]

Suggested change

	The LHE format uses an XML-like structure, but the content within the `<init>` and `<event>` blocks consists of whitespace-separated values designed for straightforward parsing in Fortran.
	The `<header>` block can contain arbitrary XML content, usually metadata or comments explaining how the events were generated.
	The following skeleton example illustrates the overall structure of an LHE file using the `pylhe` naming of the attributes
	```xml
	<LesHouchesEvents version="1.0">
	<header></header>
	<init>
	beamA beamB energyA energyB PDFgroupA PDFgroupB PDFsetA PDFsetB weightingStrategy numProcesses
	xSection error unitWeight procId
	...
	# additional hash-commented information can go here
	</init>
	<event>
	nparticles pid weight scale aqed aqcd
	id status mother1 mother2 color1 color2 px py pz e m lifetime spin
	...
	# additional hash-commented information can go here
	</event>
	...
	</LesHouchesEvents>
	```
	The table below summarizes the main parameters found in LHE files grouped by their `dataclass` representation in `pylhe`.
	| Parameter | Type | Description | Unit |
	|-----------|------|-------------|------|
	| **LHEInitInfo** | | | |
	| beamA | int | PDG ID of first beam particle | - |
	| beamB | int | PDG ID of second beam particle | - |
	| energyA | float | Energy of first beam particle | GeV |
	| energyB | float | Energy of second beam particle | GeV |
	| PDFgroupA | int | PDF group ID for first beam | - |
	| PDFgroupB | int | PDF group ID for second beam | - |
	| PDFsetA | int | PDF set ID for first beam | - |
	| PDFsetB | int | PDF set ID for second beam | - |
	| weightingStrategy | int | Weighting strategy | - |
	| numProcesses | int | Number of processes | - |
	| **LHEProcInfo** | | | |
	| xSection | float | Cross section | pb |
	| error | float | Cross section uncertainty | pb |
	| unitWeight | float | Maximum cross section. | pb |
	| procId | int | Process ID | - |
	| **LHEEventInfo** | | | |
	| nparticles | int | Number of particles in event | - |
	| pid | int | Process ID for this event | - |
	| weight | float | Event weight | - |
	| scale | float | Factorization/renormalization scale | GeV |
	| aqed | float | QED coupling constant | - |
	| aqcd | float | QCD coupling constant | - |
	| **LHEParticle** | | | |
	| id | int | PDG particle ID | - |
	| status | int | Particle status code | - |
	| mother1 | int | Index of first mother particle | - |
	| mother2 | int | Index of second mother particle | - |
	| color1 | int | First color line index | - |
	| color2 | int | Second color line index | - |
	| px | float | x-component of momentum | GeV |
	| py | float | y-component of momentum | GeV |
	| pz | float | z-component of momentum | GeV |
	| e | float | Energy | GeV |
	| m | float | Mass | GeV |
	| lifetime | float | Proper lifetime | mm |
	| spin | float | Spin information. 9.0 for unpolarized. | - |
	Further details can be found in the original definition of the Les Houches Event file standard.
	Besides the original publication there were two extensions to the LHE format, version 2.0 in 2009 [@Butterworth:2010ym] and version 3.0 in 2012 [@Andersen:2014efa].
	However, `pylhe` currently only implements the widely adopted extension from version 1.0, that is the addition of multiple weights via `<initrwgt>`, `<rwgt>`, `<weight>`,`<weights>`, `<wgt>`, and `<weightgroup>`.
	If in the future there is a demand for `<scales>`, `<generator>`, `<pdfinfo>`, or `<clustering>` support these can be added as well.

In JOSS we would consider all of this stuff that should live in the docs and not the paper. The paper exists intentionally as a citeable artifact that academic systems know how to deal with, but the project and its documentation is supposed to contain all the relevant information about the project.

[eduardo-rodrigues]

Hello. That's really great! I can only look into this next week, but will.