feat: allow passing coordinates to to_Vector*D

[Saransh-cpp]

Description

Closes #276

Adds test and docs for #278

Checklist

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't any other open Pull Requests for the required change?
• Does your submission pass pre-commit? ($ pre-commit run --all-files or $ nox -s lint)
• Does your submission pass tests? ($ pytest or $ nox -s tests)
• Does the documentation build with your changes? ($ cd docs; make clean; make html or $ nox -s docs)
• Does your submission pass the doctests? ($ xdoctest ./src/vector or $ nox -s doctests)

Before Merging

• Summarize the commit messages into a brief review of the Pull request.

[codecov-commenter]

Codecov Report

Base: 82.72% // Head: 82.87% // Increases project coverage by +0.15% 🎉

Coverage data is based on head (ae7cdc7) compared to base (17af58f).
Patch coverage: 89.47% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #319      +/-   ##
==========================================
+ Coverage   82.72%   82.87%   +0.15%     
==========================================
  Files          96       96              
  Lines       11366    11396      +30     
==========================================
+ Hits         9402     9445      +43     
+ Misses       1964     1951      -13     

Impacted Files	Coverage Δ
src/vector/_methods.py	74.68% <89.18%> (+0.53%)	⬆️
src/vector/backends/object.py	74.80% <100.00%> (ø)
src/vector/backends/awkward.py	83.03% <0.00%> (+1.50%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[jpivarski]

This looks like a good extension, with sufficient tests. I see that

• 2D → 3D
• 2D → 4D
• 3D → 4D

are all covered, and I believe this is a complete set.

I made some comments below about the error message and that more synonyms might be needed in the momentum cases. They're suggestions.

[jpivarski]

The above is helpful; maybe this is even more helpful (and it sets the tone for what the other to_Vector*D should do).

Suggested change

	raise TypeError("Only one non-None longitudinal coordinate allowed")
	raise TypeError("At most one longitudinal coordinate (`z`, `theta`, or `eta`) may be assigned (non-None)")

By the way, these to_Vector*D functions maintain momentum-ness, right? For example, is it the case that Momentum2D.to_Vector3D returns a Momentum3D?

If so, then a user might justifiably expect to pass pz instead or z, but only in the momentum case. Just something to consider, at this point.

When this gets extended to to_Vector4D, the time component has a lot of momentum synonyms. The geometric names for the two possible temporal coordinates are t and tau, but the momentum names are energy and mass, E and M, and (I think) e and m. There was a discussion once about including the lowercase as well as the uppercase.

[Saransh-cpp]

Yes, they do maintain momentum-ness. Right now the generic coordinates are automatically converted to momentum coordinates, but yes, we can explicitly add momentum coordinates as arguments in the future -

In [1]: import vector

In [2]: vector.obj(px=1, py=2).to_Vector4D(z=3, t=4)
Out[2]: MomentumObject4D(px=1, py=2, pz=3, E=4)

In [3]: vector.obj(px=1, py=2).to_Vector4D(eta=3, tau=4)
Out[3]: MomentumObject4D(px=1, py=2, eta=3, mass=4)

[jpivarski]

Similar error messages: help the user by spelling out what the longitudinal and temporal coordinates are, since the user would more likely be familiar with concrete names like z, theta, eta than "longitudinal".

[jpivarski]

Same thing.

[Saransh-cpp]

Thanks for the review! I will merge this in and tag v1.0.0!