Be explicit about the units you use

[eduardo-rodrigues]

Hi all, it seems to me that you are using MeV for energy/mass units, and in fact following the HEP system of units. May I suggest that you make this explicit in the README and also in relevant bits of docstrings?

In fact, given that Scikit-HEP and zfit are affiliated now (info to go online soon :-)), and given that we have the little and trivial hepunits package with a bunch of units and constants, would you consider making use of the package in some (at least, alternative) examples? I mean, you can have your simple examples as now but could also have other more elaborate/neat examples as extra, or in a notebook. Consider

import phasespace
from hepunits import MeV

B0_MASS = 5279.58 * MeV
PION_MASS = 139.57018 * MeV
KAON_MASS = 493.677 * MeV

weights, particles = phasespace.generate_decay(...)

[jonas-eschle]

Hi, thanks a lot for the idea and input! Thinking about it, I have the following thoughts in mind: on one hand...

• while in the examples a comment on the fact that MeV is used could be good, there is no direct need for that. It could be fantasy particles, phasespace itself is actually unitless
• the example you provided may be a little bit more confusing, since the particles may should be converted back to MeV, so it adds an additional line of code. While I fully see the need for hepunits, I am not sure how well it fits in this sort of small examples, it does not really add anything (but my biased personal impression)

on the other hand....

• regarding units, the more realistic use case (that seems worth to include in a small example) to me seems with the particle package and directly taking the values from there (and it's also up to particle to handle the units somehow)
• I really like this small packages (regarding hepunits now), they're the backbones! And stitching them together meaningfully is the key (dreaming of no more "constants.py" files in every little script folder)

I would prefer something like suggested in #23. This can be a website and/or notebook. Best seems to include several packages, e.g. particle and hepunits together with phasespace in a good, "realistic" example. And of course, directly link to it from phasespace or even display it. Since, in principle, this examples would not have to be phasespace specific, what about having a repo in scikit-hep with interaction examples? Advanced tutorials/examples making use of scikit-hep packages? (or does it exist and I've overlooked it?)

@apuignav what are your thoughts on that?

P.S: If you know of a good, small, realistic example by chance that could fit well with phasespace and hepunits, we could surely add that. The above example, I find, seems too artificial to me, or not?

[eduardo-rodrigues]

@mayou36, yes, what is suggested in https://github.com/zfit/phasespace/issues/23 seems best. We do not have such a package in the Scikit-HEP org but in fact what you suggest is something that came out during various conversations. We should probably move forward and create a package scikit-hep-examples or alike. It could in fact be scikit-hep-tutorials, thinking that we would use the repo to also have mini-tutorials on how to best use the ecosystem.

I do not find my above example artificial, just simple. I find it clear when reading it out loud. This being said, I take your point that phasespace is unitless, strictly speaking, and so it makes sense to not mix in units in basic examples in the README.

I would be happy to move forward and have examples making use of phasespace together with hepunits and Particle.

[apuignav]

I think this is the best solution. Should I close this and reference the issue when scikit-hep-tutorials are created?

[eduardo-rodrigues]

Fine by me.