Refactor spherical arg order

pyproject.toml

@@ -198,6 +198,7 @@
   messages_control.disable = [
     "cyclic-import",              # broken?
     "design",
+    "duplicate-code",
     "import-outside-toplevel",    # handled by ruff
     "fixme",
     "function-redefined",         # plum-dispatch

src/coordinax/_base.py

@@ -513,7 +513,7 @@ def components(cls) -> tuple[str, ...]:
         >>> Cartesian2DVector.components
         ('x', 'y')
         >>> SphericalVector.components
-        ('r', 'theta', 'phi')
+        ('r', 'phi', 'theta')
         >>> RadialDifferential.components
         ('d_r',)
 
@@ -618,8 +618,8 @@ def to_units(
         >>> sph.to_units({"length": "km", "angle": "deg"})
         SphericalVector(
             r=Quantity[PhysicalType('length')](value=f32[], unit=Unit("km")),
-            theta=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("deg")),
-            phi=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("deg"))
+            phi=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("deg")),
+            theta=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("deg"))
         )
 
         """
@@ -666,8 +666,8 @@ def to_units(
         >>> sph.to_units(ToUnitsOptions.consistent)
         SphericalVector(
             r=Quantity[PhysicalType('length')](value=f32[], unit=Unit("m")),
-            theta=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("deg")),
-            phi=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("deg"))
+            phi=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("rad")),
+            theta=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("rad"))
         )
 
         """

src/coordinax/_base_vec.py

@@ -173,8 +173,8 @@ def represent_as(self, target: type[VT], /, *args: Any, **kwargs: Any) -> VT:
         >>> sph
         SphericalVector(
           r=Quantity[PhysicalType('length')](value=f32[], unit=Unit("m")),
-          theta=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("rad")),
-          phi=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("rad"))
+          phi=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("rad")),
+          theta=Quantity[PhysicalType('angle')](value=f32[], unit=Unit("rad"))
         )
         >>> sph.r
         Quantity['length'](Array(3.7416575, dtype=float32), unit='m')

src/coordinax/_converters.py

@@ -0,0 +1,19 @@
+"""Representation of coordinates in different systems."""
+
+__all__: list[str] = []
+
+
+from unxt import Quantity
+
+from coordinax._typing import BatchableAngle
+
+_2pid = Quantity(360, "deg")
+
+
+def converter_phi_to_range(phi: BatchableAngle) -> BatchableAngle:
+    """Wrap the polar angle to the range [0, 2pi).
+
+    It's safe to do this conversion since this is a phase cut, unlike `theta`,
+    which is only on half the sphere.
+    """
+    return phi % _2pid

src/coordinax/_d2/builtin.py

@@ -22,6 +22,7 @@
 from .base import Abstract2DVector, Abstract2DVectorDifferential
 from coordinax._base_vec import AbstractVector
 from coordinax._checks import check_phi_range, check_r_non_negative
+from coordinax._converters import converter_phi_to_range
 from coordinax._typing import (
     BatchableAngle,
     BatchableAngularSpeed,
@@ -145,7 +146,9 @@ class PolarVector(Abstract2DVector):
     r"""Radial distance :math:`r \in [0,+\infty)`."""
 
     phi: BatchableAngle = eqx.field(
-        converter=partial(Quantity["angle"].constructor, dtype=float)
+        converter=lambda x: converter_phi_to_range(
+            Quantity["angle"].constructor(x, dtype=float)  # pylint: disable=E1120
+        )
     )
     r"""Polar angle :math:`\phi \in [0,2\pi)`."""
 
@@ -166,8 +169,8 @@ def norm(self) -> BatchableLength:
         Examples
         --------
         >>> from unxt import Quantity
-        >>> from coordinax import PolarVector
-        >>> q = PolarVector(r=Quantity(3, "kpc"), phi=Quantity(90, "deg"))
+        >>> import coordinax as cx
+        >>> q = cx.PolarVector(r=Quantity(3, "kpc"), phi=Quantity(90, "deg"))
         >>> q.norm()
         Quantity['length'](Array(3., dtype=float32), unit='kpc')
 

src/coordinax/_d3/builtin.py

@@ -24,6 +24,7 @@
 from .base import Abstract3DVector, Abstract3DVectorDifferential
 from coordinax._base_vec import AbstractVector
 from coordinax._checks import check_phi_range, check_r_non_negative, check_theta_range
+from coordinax._converters import converter_phi_to_range
 from coordinax._typing import (
     BatchableAngle,
     BatchableAngularSpeed,
@@ -88,8 +89,8 @@ def __add__(self, other: Any, /) -> "Cartesian3DVector":
         >>> from unxt import Quantity
         >>> from coordinax import Cartesian3DVector, SphericalVector
         >>> q = Cartesian3DVector.constructor(Quantity([1, 2, 3], "kpc"))
-        >>> s = SphericalVector(r=Quantity(1, "kpc"), theta=Quantity(90, "deg"),
-        ...                     phi=Quantity(0, "deg"))
+        >>> s = SphericalVector(r=Quantity(1, "kpc"), phi=Quantity(0, "deg"),
+        ...                     theta=Quantity(90, "deg"))
         >>> (q + s).x
         Quantity['length'](Array(2., dtype=float32), unit='kpc')
 
@@ -109,8 +110,8 @@ def __sub__(self, other: Any, /) -> "Cartesian3DVector":
         >>> from unxt import Quantity
         >>> from coordinax import Cartesian3DVector, SphericalVector
         >>> q = Cartesian3DVector.constructor(Quantity([1, 2, 3], "kpc"))
-        >>> s = SphericalVector(r=Quantity(1, "kpc"), theta=Quantity(90, "deg"),
-        ...                     phi=Quantity(0, "deg"))
+        >>> s = SphericalVector(r=Quantity(1, "kpc"), phi=Quantity(0, "deg"),
+        ...                     theta=Quantity(90, "deg"))
         >>> (q - s).x
         Quantity['length'](Array(0., dtype=float32), unit='kpc')
 
@@ -147,15 +148,17 @@ class SphericalVector(Abstract3DVector):
     )
     r"""Radial distance :math:`r \in [0,+\infty)`."""
 
-    theta: BatchableAngle = eqx.field(
-        converter=partial(Quantity["angle"].constructor, dtype=float)
+    phi: BatchableAngle = eqx.field(
+        converter=lambda x: converter_phi_to_range(
+            Quantity["angle"].constructor(x, dtype=float)  # pylint: disable=E1120
+        )
     )
-    r"""Inclination angle :math:`\phi \in [0,180]`."""
+    r"""Azimuthal angle :math:`\phi \in [0,360)`."""
 
-    phi: BatchableAngle = eqx.field(
+    theta: BatchableAngle = eqx.field(
         converter=partial(Quantity["angle"].constructor, dtype=float)
     )
-    r"""Azimuthal angle :math:`\phi \in [0,360)`."""
+    r"""Inclination angle :math:`\phi \in [0,180]`."""
 
     def __check_init__(self) -> None:
         """Check the validity of the initialisation."""
@@ -195,7 +198,9 @@ class CylindricalVector(Abstract3DVector):
     r"""Cylindrical radial distance :math:`\rho \in [0,+\infty)`."""
 
     phi: BatchableAngle = eqx.field(
-        converter=partial(Quantity["angle"].constructor, dtype=float)
+        converter=lambda x: converter_phi_to_range(
+            Quantity["angle"].constructor(x, dtype=float)  # pylint: disable=E1120
+        )
     )
     r"""Azimuthal angle :math:`\phi \in [0,360)`."""
 

src/coordinax/_d3/compat.py

@@ -330,8 +330,8 @@ def apysph_to_sph(obj: apyc.PhysicsSphericalRepresentation, /) -> SphericalVecto
     >>> convert(sph, cx.SphericalVector)
     SphericalVector(
       r=Quantity[...](value=f32[], unit=Unit("kpc")),
-      theta=Quantity[...](value=f32[], unit=Unit("deg")),
-      phi=Quantity[...](value=f32[], unit=Unit("deg"))
+      phi=Quantity[...](value=f32[], unit=Unit("deg")),
+      theta=Quantity[...](value=f32[], unit=Unit("deg"))
     )
 
     """

src/coordinax/_d3/transform.py

@@ -124,7 +124,19 @@ def represent_as(
 def represent_as(
     current: Cartesian3DVector, target: type[SphericalVector], /, **kwargs: Any
 ) -> SphericalVector:
-    """Cartesian3DVector -> SphericalVector."""
+    """Cartesian3DVector -> SphericalVector.
+
+    Examples
+    --------
+    >>> from unxt import Quantity
+    >>> import coordinax as cx
+
+    >>> vec = cx.Cartesian3DVector.constructor(Quantity([1, 2, 3], "km"))
+    >>> print(cx.represent_as(vec, cx.SphericalVector))
+    <SphericalVector (r[km], phi[rad], theta[rad])
+        [3.742 1.107 0.641]>
+
+    """
     r = xp.sqrt(current.x**2 + current.y**2 + current.z**2)
     theta = xp.acos(current.z / r)
     phi = xp.atan2(current.y, current.x)
@@ -135,7 +147,19 @@ def represent_as(
 def represent_as(
     current: Cartesian3DVector, target: type[CylindricalVector], /, **kwargs: Any
 ) -> CylindricalVector:
-    """Cartesian3DVector -> CylindricalVector."""
+    """Cartesian3DVector -> CylindricalVector.
+
+    Examples
+    --------
+    >>> from unxt import Quantity
+    >>> import coordinax as cx
+
+    >>> vec = cx.Cartesian3DVector.constructor(Quantity([1, 2, 3], "km"))
+    >>> print(cx.represent_as(vec, cx.CylindricalVector))
+    <CylindricalVector (rho[km], phi[rad], z[km])
+        [2.236 1.107 3.   ]>
+
+    """
     rho = xp.sqrt(current.x**2 + current.y**2)
     phi = xp.atan2(current.y, current.x)
     return target(rho=rho, phi=phi, z=current.z)
@@ -149,7 +173,20 @@ def represent_as(
 def represent_as(
     current: SphericalVector, target: type[Cartesian3DVector], /, **kwargs: Any
 ) -> Cartesian3DVector:
-    """SphericalVector -> Cartesian3DVector."""
+    """SphericalVector -> Cartesian3DVector.
+
+    Examples
+    --------
+    >>> from unxt import Quantity
+    >>> import coordinax as cx
+
+    >>> vec = cx.SphericalVector(r=Quantity(1., "kpc"), phi=Quantity(90, "deg"),
+    ...                          theta=Quantity(90, "deg"))
+    >>> print(cx.represent_as(vec, cx.Cartesian3DVector))
+    <Cartesian3DVector (x[kpc], y[kpc], z[kpc])
+        [-4.371e-08  1.000e+00 -4.371e-08]>
+
+    """
     x = current.r * xp.sin(current.theta) * xp.cos(current.phi)
     y = current.r * xp.sin(current.theta) * xp.sin(current.phi)
     z = current.r * xp.cos(current.theta)
@@ -160,7 +197,20 @@ def represent_as(
 def represent_as(
     current: SphericalVector, target: type[CylindricalVector], /, **kwargs: Any
 ) -> CylindricalVector:
-    """SphericalVector -> CylindricalVector."""
+    """SphericalVector -> CylindricalVector.
+
+    Examples
+    --------
+    >>> from unxt import Quantity
+    >>> import coordinax as cx
+
+    >>> vec = cx.SphericalVector(r=Quantity(1., "kpc"), phi=Quantity(90, "deg"),
+    ...                          theta=Quantity(90, "deg"))
+    >>> print(cx.represent_as(vec, cx.CylindricalVector))
+    <CylindricalVector (rho[kpc], phi[deg], z[kpc])
+        [ 1.000e+00  9.000e+01 -4.371e-08]>
+
+    """
     rho = xp.abs(current.r * xp.sin(current.theta))
     phi = current.phi
     z = current.r * xp.cos(current.theta)

src/coordinax/operators/_galilean/translation.py

@@ -154,8 +154,8 @@ class GalileanSpatialTranslationOperator(AbstractGalileanOperator):
     >>> vec = cx.Cartesian3DVector.constructor(q).represent_as(cx.SphericalVector)
     >>> op(vec)
     SphericalVector( r=Quantity[...](value=f32[], unit=Unit("kpc")),
-                     theta=Quantity[...](value=f32[], unit=Unit("rad")),
-                     phi=Quantity[...](value=f32[], unit=Unit("rad")) )
+                     phi=Quantity[...](value=f32[], unit=Unit("rad")),
+                     theta=Quantity[...](value=f32[], unit=Unit("rad")) )
 
     Many operators are time dependent and require a time argument. This operator
     is time independent and will pass through the time argument: