Add keyword argument for 3-vector magnitude, so that they can be constructed entirely in spherical coordinates

[christophra]

(a feature request)

The system to construct vectors is elegant: first 2D, add an argument for 3D, add another for 4D. To quote the docs

In all, there are 12 coordinate systems [in 4-space]: {x-y vs ρ-ϕ in the azimuthal plane} × {z vs θ vs η longitudinally} × {t vs τ temporally}.

But as a consequence, there is no argument to set the magnitude of a 3-vector. Using rho (or pt) remains the radius in the azimuthal (xy) plane.

• If the user knows that pt stands for "transverse momentum" (having read the docs), this is reasonably clear. But a user who knows rho from spherical coordinates could be unaware that they need to set rho = magnitude * sin(theta).
• If a 3-vector is "close" to the z-axis, any step that involves a conversion to (rho, phi, theta) introduces rounding errors. I wouldn't call a dealbreaker for a numerical library!
• If a 3-vector is aligned with the z-axis, it however stops working entirely.

Examples:

import vector
print(vector.__version__)
# 0.8.4

# Naively using `rho` in its spherical meaning
v_spherical = vector.VectorObject3D.from_rhophitheta(1, 0, 0)
print(v_spherical.z) # showing that `rho` is from cylindrical coordinates
# 1.7976931348623157e+308

# Converting the cartesian 3-vector (0,0,1) to "spherical" coordinates
v_cartesian = vector.obj(x=0, y=0, z=1)
print(v_cartesian.mag)
# 1.0
print(v_cartesian.to_rhophitheta()) # can not be represented
# vector.obj(rho=0.0, phi=0.0, theta=0.0)
print(v_cartesian.to_rhophitheta().to_xyz()) # z-component is lost in conversion
# vector.obj(x=0.0, y=0.0, z=0.0)
print(v_cartesian.to_rhophitheta().to_xyz().mag / v_cartesian.mag) # uh-oh!
# 0.0

# Rounding errors for a vector close to the z-axis
v_close = vector.obj(x=0.01, y=0.01, z=1)
print(v_close.to_rhophitheta().mag / v_close.mag) # rounding error
# 1.000000000000742

[jpivarski]

This is a feature request, and the fact that it's not the first time this has come up (see #122) means there needs to be a way to do this. Vectors can only be represented by independent blocks of azimuthal, longitudinal, and temporal coordinates, but maybe the constructors could handle "r" or "p" as a special case and construct "rho" or "pt".

Or maybe instead of the standard constructor, a special constructor? (I.e. for objects, a different function from vector.obj, maybe vector.spherical.) This idea of having special logic in the constructor can't be carried over to the Awkward Array case, which is just an interpretation of the RecordArray fields that are already there, not a computation. (RecordArrays may be buried in nested lists, and this interpretation only applies when they bubble up to the surface, so it can't be an active transformation, the way that the Object and NumPy backends are.)

In our terminology (the terminology that I've seen in most), "r" is a spherical coordinate, the 3D distance from the origin, and "rho" is a cylindrical coordinate, the 2D distance from the z-axis. I wouldn't be surprised if there are textbooks that do it the other way, but I thought the convention was fairly standard. I hope it's not confusing! (For "p" and "pt", there should be no confusion.)