feat: allow coord values in to_<coord_names> methods

[Saransh-cpp]

Description

This is a step in the direction of adding a sympy backend (so that users can pass a sympy.Symbol to these methods) and a useful feature to have for all the backends.

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? ($ pytest --doctest-plus src/vector/ or $ nox -s doctests)

Before Merging

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

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 86.38%. Comparing base (c027f99) to head (6c08b82).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #446   +/-   ##
=======================================
  Coverage   86.38%   86.38%           
=======================================
  Files          96       96           
  Lines       11139    11139           
=======================================
  Hits         9622     9622           
  Misses       1517     1517           

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

[jpivarski]

Okay, when embedding a vector (or array of vectors) in a larger-dimensional space, you're providing the ability to assign the new coordinate, rather than have it be imputed to be zero. That's a good idea.

As a nice use-case: when embedding 2D into 3D, if the new coordinate is z, chances are that a user is going to want that coordinate to be zero, but if it's theta, zero would make as much sense as $\pi/2$ or $\pi$.

In principle, a user might want to assign a whole array of new parameter values, rather than a single constant, in the case of an array of vectors. But that would be a more complicated interface, and there's value to keeping interfaces simple until required to be more complex. This interface can be expanded from scalar new parameters to array new parameters at any point in the future.

[Saransh-cpp]

I'll set it $\pi/2$ as default. Should that be the case for eta too?

No, defaults need to be guessable or memorable, and "default is always zero" is memorable, at least. I brought it up as an example in which someone would legitimately want to change the default.

eta is an "angle" that ranges from $-\infty$ to $\infty$ with eta=0 corresponding to theta=np.pi/2, so definitely don't set eta=np.pi/2 as a default! That would be some random place on the positive-z side.

The current interface does allow passing an array of new parameter values

That's great! I had missed that. So much the better.

But would it work with a nested Awkward Array of vectors and a broadcastable array of new z values? That's the kind of complication I was worried about. If it does work because Awkward naturally broadcasts, then that's great. If you need to do extra work for the Awkward case, that's not as good. If it works for NumPy and not for Awkward, that's also problematic because a user might get expectations from the NumPy backend that are not fulfilled by the Awkward backend. We don't want one backend to be an implicit promise that is not fulfilled by another backend.

[Saransh-cpp]

I missed your comment. I think you ended up editing my comment instead of replying, haha!

It works for nested awkward array of vectors too:

In [2]: v = vector.Array(
   ...:     [
   ...:         [{"x": 1, "y": 1.1, "z": 0.1}, {"x": 2, "y": 2.2, "z": 0.2}],
   ...:         [],
   ...:         [{"x": 3, "y": 3.3, "z": 0.3}],
   ...:         [
   ...:             {"x": 4, "y": 4.4, "z": 0.4},
   ...:             {"x": 5, "y": 5.5, "z": 0.5},
   ...:             {"x": 6, "y": 6.6, "z": 0.6},
   ...:         ],
   ...:     ]
   ...: )

In [3]: 

In [3]: v
Out[3]: <VectorArray3D [[{x: 1, y: 1.1, ...}, {...}], ...] type='4 * var * Vector3D...'>

In [4]: v.to_Vector4D(t=5)["t"]
Out[4]: <Array [[5, 5], [], [5], [5, 5, 5]] type='4 * var * int64'>

In [5]: v.to_Vector3D().to_Vector4D(t=[[2, 3], [], [4], [5, 6, 7]])["t"]
Out[5]: <Array [[2, 3], [], [4], [5, 6, 7]] type='4 * var * int64'>

Is there a specific example that I should try out?

[jpivarski]

That example does it! You're hiding the full array between the output of the to_Vector4D(t=[[2, 3], [], [4], [5, 6, 7]]) call and the ["t"] slice, but I assume it's making the appropriate arrays of vectors in between. If you're showing it that way because the ellipsis (...) is hiding too much, you can show expanded views with .show() (and .show(type=True)).

[Saransh-cpp]

Thanks! TIL there is a show() method for awkward arrays -

In [13]: v.to_Vector3D().to_Vector4D(t=[[2, 3], [], [4], [5, 6, 7]]).show(type=True)
type: 4 * var * Vector4D[
    x: int64,
    y: float64,
    z: float64,
    t: int64
]
[[{x: 1, y: 1.1, z: 0.1, t: 2}, {x: 2, y: 2.2, z: 0.2, t: 3}],
 [],
 [{x: 3, y: 3.3, z: 0.3, t: 4}],
 [{x: 4, y: 4.4, z: 0.4, t: 5}, {...}, {x: 6, y: 6.6, z: 0.6, t: 7}]]