coordinax.frames

Reference frames and transformations between them.

Examples

>>> import quaxed.numpy as jnp
>>> import unxt as u
>>> import coordinax as cx
>>> import coordinax.frames as cxf

>>> frame1 = cxf.Alice()
>>> frame2 = cxf.Bob()

Let’s transform a position from Alice’s frame to Bob’s frame:

>>> op = cxf.frame_transform_op(frame1, frame2)
>>> op
Pipe((
    GalileanSpatialTranslation(CartesianPos3D( ... )),
    GalileanBoost(CartesianVel3D( ... ))
))

>>> q_alice = cx.CartesianPos3D.from_([0, 0, 0], "km")
>>> t = u.Quantity(2.5, "yr")
>>> _, q_bob = op(t, q_alice)
>>> print(q_bob)
<CartesianPos3D: (x, y, z) [km]
    [2.129e+13 1.000e+04 0.000e+00]>

Now let’s create a new transformed frame and work with it:

>>> R = cx.ops.GalileanRotation([[0., -1, 0], [1, 0, 0], [0, 0, 1]])
>>> frame = cxf.TransformedReferenceFrame(frame1, R)
>>> frame
TransformedReferenceFrame(
    base_frame=Alice(), xop=GalileanRotation(rotation=f32[3,3])
)

Let’s transform a position from the base frame to the transformed frame:

>>> op = cxf.frame_transform_op(cxf.Alice(), frame)

>>> q_icrs = cx.CartesianPos3D.from_([1, 0, 0], "kpc")
>>> q_frame = op(q_icrs)
>>> print(q_frame)
<CartesianPos3D: (x, y, z) [kpc]
    [ 0. -1.  0.]>

>>> op.inverse(q_frame) == q_icrs
Array(True, dtype=bool)

This can also transform a velocity:

>>> v_icrs = cx.CartesianVel3D.from_([1, 0, 0], "km/s")
>>> q_frame, v_frame = op(q_icrs, v_icrs)
>>> print(q_frame, v_frame, sep="\n")
<CartesianPos3D: (x, y, z) [kpc]
    [ 0. -1.  0.]>
<CartesianVel3D: (x, y, z) [km / s]
    [ 0. -1.  0.]>

>>> op.inverse(q_frame, v_frame) == (q_icrs, v_icrs)
True

class coordinax.frames.AbstractReferenceFrame

Bases: Module

Base class for all reference frames.

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

exception coordinax.frames.FrameTransformError

Bases: Exception

An error occurred during a frame transformation.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class coordinax.frames.NoFrame

Bases: AbstractReferenceFrame

A null reference frame.

This is a reference frame that cannot be transformed to or from.

Examples

>>> import coordinax.frames as cxf

>>> null = cxf.NoFrame()
>>> alice = cxf.Alice()

>>> try:
...     cxf.frame_transform_op(null, alice)
... except cxf.FrameTransformError as e:
...     print(e)
Cannot transform from the null frame.

>>> try:
...     cxf.frame_transform_op(alice, null)
... except cxf.FrameTransformError as e:
...     print(e)
Cannot transform to the null frame.

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

class coordinax.frames.TransformedReferenceFrame(base_frame: FrameT, xop: AbstractOperator)

Bases: AbstractReferenceFrame, Generic[FrameT]

Transformations relative to a base reference frame.

This class represents a reference frame that is defined relative to a base reference frame. The transformation from the base reference frame to this reference frame is stored as an coordinax.operators.AbstractOperator.

:::{warning}

The transformation operator ops is the transformation of the frames, not the coordinates. This is a passive (intrinsic) versus active (extrinsic) transformation. A frame transformation (passive) is applied to the coordinates by the inverse of the operator.

::

.. rubric:: Examples

>>> import quaxed.numpy as jnp
>>> import coordinax as cx
>>> import coordinax.frames as cxf

>>> R = cx.ops.GalileanRotation([[0., -1, 0], [1, 0, 0], [0, 0, 1]])
>>> frame = cxf.TransformedReferenceFrame(cxf.ICRS(), R)
>>> frame
TransformedReferenceFrame(
  base_frame=ICRS(), xop=GalileanRotation(rotation=f32[3,3])
)

Let’s transform a position from the base frame to the transformed frame:

>>> op = cxf.frame_transform_op(cxf.ICRS(), frame)

>>> q_icrs = cx.CartesianPos3D.from_([1, 0, 0], "kpc")
>>> q_frame = op(q_icrs)
>>> print(q_frame)
<CartesianPos3D: (x, y, z) [kpc]
    [ 0. -1.  0.]>

>>> op.inverse(q_frame) == q_icrs
Array(True, dtype=bool)

This can also transform a velocity:

>>> v_icrs = cx.CartesianVel3D.from_([1, 0, 0], "km/s")
>>> q_frame, v_frame = op(q_icrs, v_icrs)
>>> print(q_frame, v_frame, sep="\n")
<CartesianPos3D: (x, y, z) [kpc]
    [ 0. -1.  0.]>
<CartesianVel3D: (x, y, z) [km / s]
    [ 0. -1.  0.]>

>>> op.inverse(q_frame, v_frame) == (q_icrs, v_icrs)
True

Parameters:

• base_frame (TypeVar(FrameT, bound= AbstractReferenceFrame))

• xop (AbstractOperator)

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

base_frame: TypeVar(FrameT, bound= AbstractReferenceFrame)

The base reference frame.

xop: AbstractOperator

The transformation from the base frame to this frame. This is a passive transformation, describing the transformation of the frame, not the coordinates. To transform the coordinates, apply the inverse of this operator.

coordinax.frames.frame_transform_op(from_frame: Any, to_frame: Any, /)

Make a frame transform.

Parameters:

• from_frame (AbstractReferenceFrame) – The reference frame to transform from.

• to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Return type:

Any

Examples

>>> import unxt as u
>>> import coordinax.vecs as cxv
>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()

>>> op = cxf.frame_transform_op(alice, bob)
>>> op
Pipe(( ... ))

>>> q = cxv.CartesianPos3D.from_([1, 2, 3], "kpc")
>>> t = u.Quantity(1, "yr")
>>> print(op(t, q)[1])
<CartesianPos3D: (x, y, z) [kpc]
    [1. 2. 3.]>

coordinax.frames.frame_transform_op(from_frame: AbstractReferenceFrame, to_frame: TransformedReferenceFrame) → AbstractOperator

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return a frame transform operator to a transformed frame.

Examples

>>> import quaxed.numpy as jnp
>>> import coordinax as cx
>>> import coordinax.frames as cxf

>>> R = cx.ops.GalileanRotation([[0., -1, 0], [1, 0, 0], [0, 0, 1]])
>>> frame = cxf.TransformedReferenceFrame(cxf.ICRS(), R)
>>> frame
TransformedReferenceFrame(
  base_frame=ICRS(), xop=GalileanRotation(rotation=f32[3,3])
)

Let’s transform a position from the base frame to the transformed frame:

>>> op = cxf.frame_transform_op(cxf.ICRS(), frame)

>>> q_icrs = cx.CartesianPos3D.from_([1, 0, 0], "kpc")
>>> q_frame = op(q_icrs)
>>> print(q_frame)
<CartesianPos3D: (x, y, z) [kpc]
    [ 0. -1.  0.]>

coordinax.frames.frame_transform_op(from_frame: TransformedReferenceFrame, to_frame: AbstractReferenceFrame) → AbstractOperator

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return a frame transform operator from a transformed frame.

Examples

>>> import quaxed.numpy as jnp
>>> import coordinax as cx
>>> import coordinax.frames as cxf

>>> R = cx.ops.GalileanRotation([[0., -1, 0], [1, 0, 0], [0, 0, 1]])
>>> frame = cxf.TransformedReferenceFrame(cxf.ICRS(), R)
>>> frame
TransformedReferenceFrame(
  base_frame=ICRS(), xop=GalileanRotation(rotation=f32[3,3])
)

Let’s transform a position from the base frame to the transformed frame:

>>> op = cxf.frame_transform_op(frame, cxf.ICRS())

>>> q_icrs = cx.CartesianPos3D.from_([0, -1, 0], "kpc")
>>> q_frame = op(q_icrs)
>>> print(q_frame)
<CartesianPos3D: (x, y, z) [kpc]
    [1. 0. 0.]>

coordinax.frames.frame_transform_op(from_frame: TransformedReferenceFrame, to_frame: TransformedReferenceFrame) → AbstractOperator

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return a frame transform operator between two transformed frames.

Examples

>>> import quaxed.numpy as jnp
>>> import coordinax as cx
>>> import coordinax.frames as cxf

>>> R = cx.ops.GalileanRotation([[0., -1, 0], [1, 0, 0], [0, 0, 1]])
>>> frame1 = cxf.TransformedReferenceFrame(cxf.ICRS(), R)

>>> shift = cx.ops.GalileanSpatialTranslation.from_([1, 0, 0], "kpc")
>>> frame2 = cxf.TransformedReferenceFrame(frame1, shift)

>>> op1to2 = cxf.frame_transform_op(frame1, frame2)

>>> q_frame1 = cx.CartesianPos3D.from_([0, -1, 0], "kpc")
>>> q_frame2 = op1to2(q_icrs)

coordinax.frames.frame_transform_op(from_frame: AbstractReferenceFrame, to_frame: AbstractReferenceFrame, /) → Identity

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return an identity operator for frames that are the same.

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.frame_transform_op(alice, alice)
Identity()

>>> friend = cxf.FriendOfAlice()
>>> cxf.frame_transform_op(friend, friend)
Identity()

>>> bob = cxf.Bob()
>>> cxf.frame_transform_op(bob, bob)
Identity()

coordinax.frames.frame_transform_op(from_frame: Alice, to_frame: FriendOfAlice, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Transform from Alice’s frame to Bob’s frame.

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> alice = cx.frames.Alice()
>>> friend = cx.frames.FriendOfAlice()

>>> op = cx.frames.frame_transform_op(alice, friend)
>>> print(op)
Pipe((
  GalileanSpatialTranslation(<CartesianPos3D: (x, y, z) [m]
      [10  0  0]>),
  GalileanRotation([[ 0.         -0.99999994  0.        ]
                    [ 0.99999994  0.          0.        ]
                    [ 0.          0.          0.99999994]])
))

>>> q_alice = cx.vecs.CartesianPos3D.from_([0, 0, 0], "m")
>>> q_friend = op(u.Quantity(1, "s"), q_alice)
>>> q_friend
(Quantity(Array(1, dtype=int32, weak_type=True), unit='s'),
 CartesianPos3D( x=Quantity(0., unit='m'), y=Quantity(9.999999, unit='m'),
                 z=Quantity(0., unit='m')
 ))

coordinax.frames.frame_transform_op(from_frame: Alice, to_frame: Bob, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Transform from Alice’s frame to Bob’s frame.

Examples

>>> import unxt as u
>>> import coordinax.vecs as cxv
>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()

>>> op = cxf.frame_transform_op(alice, bob)
>>> print(op)
Pipe((
  GalileanSpatialTranslation(<CartesianPos3D: (x, y, z) [km]
      [100000  10000      0]>),
  GalileanBoost(<CartesianVel3D: (x, y, z) [m / s]
      [2.698e+08 0.000e+00 0.000e+00]>)
))

>>> q = cxv.CartesianPos3D.from_([0, 0, 0], "m")

>>> q_bob = op(u.Quantity(0, "s"), q)
>>> q_bob
(Quantity(Array(0, dtype=int32, weak_type=True), unit='s'),
 CartesianPos3D( x=Quantity(1.e+08, unit='m'), ... z=Quantity(0., unit='m')
))

>>> q_bob = op(u.Quantity(1, "s"), q)
>>> q_bob
(Quantity(Array(1, dtype=int32, weak_type=True), unit='s'),
 CartesianPos3D( x=Quantity(3.6981322e+08, unit='m'), ... z=Quantity(0., unit='m')
))

coordinax.frames.frame_transform_op(from_frame: AbstractReferenceFrame, to_frame: AbstractReferenceFrame, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Transform back.

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> alice = cx.frames.Alice()
>>> friend = cx.frames.FriendOfAlice()

>>> op = cx.frames.frame_transform_op(friend, alice)
>>> print(op)
Pipe((
  GalileanRotation([[ 0.          0.99999994  0.        ]
                    [-0.99999994  0.          0.        ]
                    [ 0.          0.          0.99999994]]),
  GalileanSpatialTranslation(<CartesianPos3D: (x, y, z) [m]
      [-10   0   0]>)
))

>>> q_friend = cx.vecs.CartesianPos3D.from_([0, 0, 0], "m")
>>> q_alice = op(u.Quantity(1, "s"), q_friend)
>>> q_alice
(Quantity(Array(1, dtype=int32, weak_type=True), unit='s'),
 CartesianPos3D( x=Quantity(-10., unit='m'), y=Quantity(0., unit='m'),
                 z=Quantity(0., unit='m')
))

coordinax.frames.frame_transform_op(from_frame: NoFrame, to_frame: AbstractReferenceFrame, /) → NoReturn

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Cannot transform from the null frame.

Examples

>>> import coordinax.frames as cxf

>>> null = cxf.NoFrame()
>>> alice = cxf.Alice()

>>> try:
...     cxf.frame_transform_op(null, alice)
... except cxf.FrameTransformError as e:
...     print(e)
Cannot transform from the null frame.

coordinax.frames.frame_transform_op(from_frame: AbstractReferenceFrame, to_frame: NoFrame, /) → NoReturn

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Cannot transform to the null frame.

Examples

>>> import coordinax.frames as cxf

>>> null = cxf.NoFrame()
>>> alice = cxf.Alice()

>>> try:
...     cxf.frame_transform_op(alice, null)
... except cxf.FrameTransformError as e:
...     print(e)
Cannot transform to the null frame.

coordinax.frames.frame_transform_op(from_frame: AbstractSpaceFrame, to_frame: AbstractSpaceFrame, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Compute frame transformations with ICRS as the intermediary.

Examples

>>> from plum import dispatch
>>> import unxt as u
>>> import coordinax as cx

>>> class MySpaceFrame(cx.frames.AbstractSpaceFrame):
...     pass

>>> @dispatch
... def frame_transform_op(from_frame: MySpaceFrame, to_frame: ICRS, /) -> cx.ops.AbstractOperator:
...     return cx.ops.GalileanRotation.from_euler("z", u.Quantity(10, "deg"))

We can transform from MySpaceFrame to a Galacocentric frame, even though we don’t have a direct transformation defined:

>>> my_frame = MySpaceFrame()
>>> gcf_frame = cx.frames.Galactocentric()

>>> op = cx.frames.frame_transform_op(my_frame, gcf_frame)
>>> op
Pipe((
    GalileanRotation(rotation=f32[3,3]),
    ...
))

coordinax.frames.frame_transform_op(from_frame: ICRS, to_frame: ICRS, /) → Identity

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return an identity operator for the ICRS->ICRS transformation.

Examples

>>> import coordinax.frames as cxf
>>> icrs_frame = cxf.ICRS()
>>> frame_op = cxf.frame_transform_op(icrs_frame, icrs_frame)
>>> frame_op
Identity()

coordinax.frames.frame_transform_op(from_frame: Galactocentric, to_frame: Galactocentric, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return a sequence of operators for the Galactocentric frame self transformation.

Examples

>>> import unxt as u
>>> import coordinax.frames as cxf

>>> gcf_frame = cxf.Galactocentric()
>>> frame_op = cxf.frame_transform_op(gcf_frame, gcf_frame)
>>> frame_op
Pipe(Identity())

>>> gcf_frame2 = cxf.Galactocentric(roll=u.Quantity(10, "deg"))
>>> frame_op2 = cxf.frame_transform_op(gcf_frame, gcf_frame2)
>>> frame_op2
Pipe((
    VelocityBoost(CartesianVel3D( ... )),
    GalileanRotation(rotation=f32[3,3]),
    GalileanSpatialTranslation(CartesianPos3D( ... )),
    GalileanRotation(rotation=f32[3,3]),
    GalileanRotation(rotation=f32[3,3]),
    GalileanSpatialTranslation(CartesianPos3D( ... )),
    GalileanRotation(rotation=f32[3,3]),
    VelocityBoost(CartesianVel3D( ... ))
))

coordinax.frames.frame_transform_op(from_frame: ICRS, to_frame: Galactocentric, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return an ICRS to Galactocentric frame transformation operator.

Examples

For this example we compare against the Astropy implementation of the frame transformation:

>>> import unxt as u
>>> import coordinax as cx
>>> import astropy.coordinates as apyc

The location of Vega in ICRS coordinates:

>>> vega = apyc.SkyCoord(
...     ra=279.23473479 * u.unit("deg"), dec=38.78368896 * u.unit("deg"),
...     distance=25 * u.unit("pc"),
...     pm_ra_cosdec=200 * u.unit("mas / yr"), pm_dec=-286 * u.unit("mas / yr"),
...     radial_velocity=-13.9 * u.unit("km / s"))
>>> print(vega)
<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, pc)
    (279.23473479, 38.78368896, 25.)
 (pm_ra_cosdec, pm_dec, radial_velocity) in (mas / yr, mas / yr, km / s)
    (200., -286., -13.9)>

Transforming to a Galactocentric frame:

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
    (266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> vega.transform_to(apy_gcf)
<SkyCoord (Galactocentric: ...): (x, y, z) in pc
    (-8112.89970167, 21.79911216, 29.01384942)
 (v_x, v_y, v_z) in km / s
    (34.06711868, 234.61647066, -28.75976702)>

Now we can use coordinax to perform the same transformation!

Converting the Astropy objects to coordinax:

>>> vega_q = cx.vecs.LonLatSphericalPos.from_(vega.icrs.data)
>>> vega_p = cx.vecs.LonCosLatSphericalVel.from_(vega.icrs.data.differentials["s"])

>>> icrs_frame = cx.frames.ICRS()
>>> gcf_frame = cx.frames.Galactocentric.from_(apy_gcf)

Define the transformation operator:

>>> frame_op = cx.frames.frame_transform_op(icrs_frame, gcf_frame)
>>> frame_op
Pipe((
    GalileanRotation(rotation=f32[3,3]),
    GalileanSpatialTranslation(CartesianPos3D( ... )),
    GalileanRotation(rotation=f32[3,3]),
    VelocityBoost(CartesianVel3D( ... ))
))

Apply the transformation:

>>> vega_gcf_q, vega_gcf_p = frame_op(vega_q, vega_p)
>>> vega_gcf_q = vega_gcf_q.vconvert(cx.vecs.CartesianPos3D)
>>> vega_gcf_p = vega_gcf_p.vconvert(cx.vecs.CartesianVel3D, vega_gcf_q)
>>> print(vega_gcf_q)
<CartesianPos3D: (x, y, z) [pc]
    [-8112.898    21.799    29.01...]>
>>> print(vega_gcf_p.uconvert({u.dimension("speed"): "km/s"}))
<CartesianVel3D: (x, y, z) [km / s]
    [ 34.067 234.616 -28.76 ]>

It matches!

Let’s do it again for a few different input types:

>>> q = u.Quantity([0, 0, 0], "pc")
>>> frame_op(q)
Quantity(Array([-8121.972, 0. , 20.8 ], dtype=float32), unit='pc')

>>> p = u.Quantity([0., 0, 0], "km/s")

>>> newq, newp = frame_op(q, p)
>>> newq, newp
(Quantity(Array([-8121.972,     0.   ,    20.8  ], dtype=float32), unit='pc'),
 Quantity(Array([ 12.9 , 245.6 ,   7.78], dtype=float32), unit='km / s'))

>>> q = cx.CartesianPos3D.from_([0, 0, 0], "pc")
>>> p = cx.CartesianVel3D.from_([0, 0, 0], "km/s")

>>> newq, newp = frame_op(q, p)
>>> print(newq, newp, sep="\n")
<CartesianPos3D: (x, y, z) [pc]
    [-8121.972     0.       20.8  ]>
<CartesianVel3D: (x, y, z) [km / s]
    [ 12.9  245.6    7.78]>

coordinax.frames.frame_transform_op(from_frame: Galactocentric, to_frame: ICRS, /) → Pipe

Parameters:

• from_frame (Any)

• to_frame (Any)

Return type:

Any

Return a Galactocentric to ICRS frame transformation operator.

Examples

For this example we compare against the Astropy implementation of the frame transformation:

>>> import unxt as u
>>> import coordinax as cx
>>> import astropy.coordinates as apyc

The location of Vega in Galactocentric coordinates:

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
    (266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> vega = apyc.SkyCoord(
...     ra=279.23473479 * u.unit("deg"), dec=38.78368896 * u.unit("deg"),
...     distance=25 * u.unit("pc"),
...     pm_ra_cosdec=200 * u.unit("mas / yr"), pm_dec=-286 * u.unit("mas / yr"),
...     radial_velocity=-13.9 * u.unit("km / s")
... ).transform_to(apy_gcf)
>>> print(vega)
<SkyCoord (Galactocentric: ...): (x, y, z) in pc
    (-8112.89970167, 21.79911216, 29.01384942)
 (v_x, v_y, v_z) in km / s
    (34.06711868, 234.61647066, -28.75976702)>

Transforming to an ICRS frame:

>>> vega.transform_to(apyc.ICRS())
<SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, pc)
    (279.23473479, 38.78368896, 25.)
 (pm_ra_cosdec, pm_dec, radial_velocity) in (mas / yr, mas / yr, km / s)
    (200., -286., -13.9)>

Now we can use coordinax to perform the same transformation!

Converting the Astropy objects to coordinax:

>>> vega_q = cx.CartesianPos3D.from_(vega.galactocentric.data)
>>> vega_p = cx.CartesianVel3D.from_(vega.galactocentric.data.differentials["s"])

>>> icrs_frame = cx.frames.ICRS()
>>> gcf_frame = cx.frames.Galactocentric.from_(apy_gcf)

Define the transformation operator:

>>> frame_op = cx.frames.frame_transform_op(gcf_frame, icrs_frame)

Apply the transformation:

>>> vega_icrs_q, vega_icrs_p = frame_op(vega_q, vega_p)

>>> vega_icrs_q = vega_icrs_q.vconvert(cx.vecs.LonLatSphericalPos)
>>> vega_icrs_p = vega_icrs_p.vconvert(cx.vecs.LonCosLatSphericalVel, vega_icrs_q)
>>> print(vega_icrs_q.uconvert({u.dimension("angle"): "deg", u.dimension("length"): "pc"}))
<LonLatSphericalPos: (lon[deg], lat[deg], distance[pc])
    [279.235  38.784  25.   ]>
>>> print(vega_icrs_p.uconvert({u.dimension("angular speed"): "mas / yr", u.dimension("speed"): "km/s"}))
<LonCosLatSphericalVel: (lon_coslat[mas / yr], lat[mas / yr], distance[km / s])
    [ 200.001 -286.  -13.9  ]>

It matches!

Let’s do it again for a few different input types:

>>> q = u.Quantity([0, 0, 0], "pc")
>>> frame_op(q).round(0)
Quantity(Array([ -446., -7094., -3930.], dtype=float32), unit='pc')

>>> p = u.Quantity([0., 0, 0], "km/s")

>>> newq, newp = frame_op(q, p)
>>> newq.round(0), newp.round(0)
(Quantity(Array([ -446., -7094., -3930.], dtype=float32), unit='pc'),
 Quantity(Array([-114.,  122., -181.], dtype=float32), unit='km / s'))

>>> q = cx.CartesianPos3D.from_([0, 0, 0], "pc")
>>> p = cx.CartesianVel3D.from_([0, 0, 0], "km/s")

>>> newq, newp = frame_op(q, p)
>>> print(newq, newp, sep="\n")
<CartesianPos3D: (x, y, z) [pc]
    [ -445.689 -7094.056 -3929.708]>
<CartesianVel3D: (x, y, z) [km / s]
    [-113.868  122.047 -180.79 ]>

coordinax.frames.frame_of(obj: Any, /)

Get the frame of an object.

coordinax.frames.frame_of(obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

Any

Get the frame of an coordinax.frames.AbstractReferenceFrame.

Examples

>>> import coordinax.frames as cxf
>>> frame = cxf.ICRS()
>>> frame_of(frame) is frame
True

coordinax.frames.frame_of(obj: AbstractCoordinate) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

Any

Return the frame of the coordinate.

Examples

>>> import coordinax as cx

>>> coord = cx.Coordinate(cx.CartesianPos3D.from_([1, 2, 3], "kpc"),
...                       cx.frames.ICRS())
>>> cx.frames.frame_of(coord)
ICRS()

Parameters:

obj (Any)

Return type:

Any

class coordinax.frames.Alice

Bases: AbstractReferenceFrame

A stationary lab reference frame.

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()

>>> op = cxf.frame_transform_op(alice, bob)
>>> print(op)
Pipe((
  GalileanSpatialTranslation(<CartesianPos3D: (x, y, z) [km]
      [100000  10000      0]>),
  GalileanBoost(<CartesianVel3D: (x, y, z) [m / s]
      [2.698e+08 0.000e+00 0.000e+00]>)
))

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

class coordinax.frames.FriendOfAlice

Bases: AbstractReferenceFrame

A reference frame shifted from Alice’s frame.

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

class coordinax.frames.Bob

Bases: AbstractReferenceFrame

A moving reference frame.

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()

>>> op = cxf.frame_transform_op(alice, bob)
>>> print(op)
Pipe((
  GalileanSpatialTranslation(<CartesianPos3D: (x, y, z) [km]
      [100000  10000      0]>),
  GalileanBoost(<CartesianVel3D: (x, y, z) [m / s]
      [2.698e+08 0.000e+00 0.000e+00]>)
))

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

class coordinax.frames.AbstractCoordinate

Bases: AbstractVector

Coordinates are vectors in a reference frame.

See also

None

property T: Self

Transpose the vector.

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can transpose a vector:

>>> vec = cx.CartesianPos3D(x=u.Quantity([[0, 1], [2, 3]], "m"),
...                         y=u.Quantity([[0, 1], [2, 3]], "m"),
...                         z=u.Quantity([[0, 1], [2, 3]], "m"))
>>> vec.T.x
Quantity(Array([[0, 2],
                          [1, 3]], dtype=int32), unit='m')

asdict(*, dict_factory: ~collections.abc.Callable[[~typing.Any], ~collections.abc.Mapping[str, ~unxt._src.quantity.base.AbstractQuantity]] = <class 'dict'>)

Return the vector as a Mapping.

Parameters:

dict_factory (Callable[[Any], Mapping[str, AbstractQuantity]]) – The type of the mapping to return.

Returns:

The vector as a mapping.

Return type:

Mapping[str, Quantity]

See also

None

This applies recursively to the components of the vector.

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can get the vector as a mapping:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.asdict()
{'x': Quantity(Array([[1, 2], [3, 4]], dtype=int32), unit='m'),
 'y': Quantity(Array(0, dtype=int32, ...), unit='m')}

astype(dtype: Any, /, **kwargs: Any)

Cast the vector to a new dtype.

Parameters:

• dtype (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

components = ()

copy()

Return a copy of the vector.

Return type:

Self

Examples

>>> import coordinax as cx

>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> print(vec.copy())
<CartesianPos3D: (x, y, z) [m]
    [1 2 3]>

property devices: MappingProxyType

Get the devices of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.devices
mappingproxy({'x': CpuDevice(id=0), 'y': CpuDevice(id=0),
              'z': CpuDevice(id=0)})

dimensions = {}

property dtype

property dtypes: MappingProxyType

Get the dtypes of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.dtypes
mappingproxy({'x': dtype('int32'), 'y': dtype('int32'),
              'z': dtype('int32')})

flatten()

Flatten the vector.

Return type:

Self

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.shape
(2, 2)

>>> vec.flatten().shape
(4,)

classmethod from_(cls: type[AbstractVectorLike], *args: Any, **kwargs: Any)

Create a vector-like object from arguments.

Examples

>>> import coordinax.vecs as cxv

>>> q = cxv.CartesianPos3D.from_([1, 2, 3], "m")
>>> print(q)
<CartesianPos3D: (x, y, z) [m]
    [1 2 3]>

>>> v = cxv.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> print(v)
<CartesianVel3D: (x, y, z) [m / s]
    [1 2 3]>

>>> space = cxv.KinematicSpace.from_(q)
>>> print(space)
KinematicSpace({
 'length': <CartesianPos3D: (x, y, z) [m]
               [1 2 3]>
})

from_(cls: type[AbstractVector], *args: Any, **kwargs: Any) → AbstractVector

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Create a vector from arguments.

See coordinax.vector for more information.

from_(cls: type[KinematicSpace], obj: KinematicSpace, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a Space, returning the KinematicSpace.

Examples

>>> import coordinax as cx

>>> q = cx.KinematicSpace.from_(cx.CartesianPos3D.from_([1, 2, 3], "m"))
>>> cx.KinematicSpace.from_(q) is q
True

from_(cls: type[KinematicSpace], obj: AbstractPos, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a coordinax.KinematicSpace from a coordinax.AbstractPos.

Examples

>>> import coordinax as cx

>>> q = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> w = cx.KinematicSpace.from_(q)
>>> w
KinematicSpace({ 'length': CartesianPos3D( ... ) })

from_(cls: type[KinematicSpace], q: AbstractPos, p: AbstractVel, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a coordinax.KinematicSpace from a coordinax.AbstractPos.

Examples

>>> import coordinax as cx

>>> q = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> p = cx.CartesianVel3D.from_([4, 5, 6], "m/s")
>>> w = cx.KinematicSpace.from_(q, p)
>>> w
KinematicSpace({ 'length': CartesianPos3D( ... ), 'speed': CartesianVel3D( ... ) })

from_(cls: type[KinematicSpace], q: AbstractPos, p: AbstractVel, a: AbstractAcc, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a coordinax.KinematicSpace from a coordinax.AbstractPos.

Examples

>>> import coordinax as cx

>>> q = cx.vecs.CartesianPos3D.from_([1, 2, 3], "m")
>>> p = cx.vecs.CartesianVel3D.from_([4, 5, 6], "m/s")
>>> a = cx.vecs.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> w = cx.KinematicSpace.from_(q, p, a)
>>> w
KinematicSpace({ 'length': CartesianPos3D( ... ),
        'speed': CartesianVel3D( ... ),
        'acceleration': CartesianAcc3D( ... ) })

from_(cls: type[KinematicSpace], obj: Mapping[str, Any]) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a KinematicSpace from a Mapping.

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> space = cx.KinematicSpace.from_({ 'length': u.Quantity([1, 2, 3], "m") })
>>> print(space)
KinematicSpace({
   'length': <CartesianPos3D: (x, y, z) [m]
       [1 2 3]>
})

Parameters:

• cls (type[AbstractVectorLike])

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

property mT: Self

Transpose the vector.

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can transpose a vector:

>>> vec = cx.CartesianPos3D(x=u.Quantity([[0, 1], [2, 3]], "m"),
...                         y=u.Quantity([[0, 1], [2, 3]], "m"),
...                         z=u.Quantity([[0, 1], [2, 3]], "m"))
>>> vec.mT.x
Quantity(Array([[0, 2],
                          [1, 3]], dtype=int32), unit='m')

property ndim: int

Number of array dimensions (axes).

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can get the number of dimensions of a vector:

>>> vec = cx.vecs.CartesianPos2D.from_([1, 2], "m")
>>> vec.ndim
0

>>> vec = cx.vecs.CartesianPos2D.from_([[1, 2], [3, 4]], "m")
>>> vec.ndim
1

ndim is calculated from the broadcasted shape. We can see this by creating a 2D vector in which the components have different shapes:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.ndim
2

ravel()

Ravel the vector.

Return type:

Self

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.shape
(2, 2)

>>> vec.ravel().shape
(4,)

represent_as(target: type, *args: Any, **kwargs: Any)

Represent the vector as another type.

This just forwards to coordinax.vconvert.

Parameters:

• target (type[coordinax.AbstractVel]) – The type to represent the vector as.

• *args (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

• **kwargs (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

Return type:

Any

Examples

>>> import coordinax as cx

Transforming a Position:

>>> q_cart = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> q_sph = q_cart.represent_as(cx.SphericalPos)
>>> q_sph
SphericalPos( ... )
>>> q_sph.r
Distance(Array(3.7416575, dtype=float32), unit='m')

Transforming a Velocity:

>>> v_cart = cx.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> v_sph = v_cart.represent_as(cx.SphericalVel, q_cart)
>>> v_sph
SphericalVel( ... )

Transforming an Acceleration:

>>> a_cart = cx.vecs.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> a_sph = a_cart.represent_as(cx.vecs.SphericalAcc, v_cart, q_cart)
>>> print(a_sph)
<SphericalAcc: (r[m / s2], theta[rad / s2], phi[rad / s2])
    [13.363  0.767 -1.2  ]>

reshape(*shape: Any, order: str = 'C')

Reshape the components of the vector.

Parameters:

• *shape (Any) – The new shape.

• order (str) – The order to use for the reshape.

Return type:

Self

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can reshape a vector:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))

>>> vec.reshape(4)
CartesianPos2D(x=Quantity([1, 2, 3, 4], unit='m'),
               y=Quantity([0, 0, 0, 0], unit='m'))

round(decimals: int = 0)

Round the components of the vector.

Parameters:

decimals (int) – The number of decimals to round to.

Return type:

Self

Examples

>>> import unxt as u
>>> import coordinax as cx

We can round a vector:

>>> vec = cx.vecs.CartesianPos2D.from_([[1.1, 2.2], [3.3, 4.4]], "m")
>>> vec.round(0)
CartesianPos2D(x=Quantity([1., 3.], unit='m'), y=Quantity([2., 4.], unit='m'))

property shape: tuple[int, ...]

Return the shape of the vector.

Examples

>>> import unxt as u
>>> import coordinax as cx

We can get the shape of a vector:

>>> vec = cx.vecs.CartesianPos1D(x=u.Quantity([1, 2], "m"))
>>> vec.shape
(2,)

>>> vec = cx.vecs.CartesianPos1D(x=u.Quantity([[1, 2], [3, 4]], "m"))
>>> vec.shape
(2, 2)

shape is calculated from the broadcasted shape. We can see this by creating a 2D vector in which the components have different shapes:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.shape
(2, 2)

>>> space = cx.KinematicSpace(length=vec)
>>> space.shape
(2, 2)

property shapes: MappingProxyType

Get the shapes of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.shapes
mappingproxy({'x': (), 'y': (), 'z': ()})

property size

property sizes: MappingProxyType

Get the sizes of the vector’s components.

Examples

>>> import coordinax as cx

>>> cx.vecs.CartesianPos2D.from_([1, 2], "m").sizes
mappingproxy({'x': 1, 'y': 1})

>>> cx.vecs.CartesianPos2D.from_([[1, 2], [1, 2]], "m").sizes
mappingproxy({'x': 2, 'y': 2})

to_device(device: None | Device = None)

Move the vector to a new device.

Examples

>>> from jax import devices
>>> import unxt as u
>>> import coordinax as cx

We can move a vector to a new device:

>>> vec = cx.vecs.CartesianPos1D(u.Quantity([1, 2], "m"))
>>> vec.to_device(devices()[0])
CartesianPos1D(x=Quantity([1, 2], unit='m'))

Parameters:

device (None | Device)

Return type:

Self

to_frame(toframe: AbstractReferenceFrame, /, t: Quantity | None = None)

Transform the coordinate to a specified frame.

Examples

>>> import coordinax as cx

>>> cicrs = cx.Coordinate(cx.CartesianPos3D.from_([1, 2, 3], "kpc"),
...                       cx.frames.ICRS())

>>> cicrs.to_frame(cx.frames.ICRS()) is cicrs
True

>>> cgcf = cicrs.to_frame(cx.frames.Galactocentric())
>>> cgcf
Coordinate(
    KinematicSpace({ 'length': CartesianPos3D( ... ) }),
    frame=Galactocentric( ... )
)

Parameters:

• toframe (AbstractReferenceFrame)

• t (Quantity | None)

Return type:

AbstractCoordinate

uconvert(*args: Any, **kw: Any)

Convert the vector to the given units.

This just forwards to unxt.uconvert, reversing the order of the arguments to match the unxt API.

Examples

>>> import coordinax as cx

>>> vec = cx.vecs.CartesianPos3D.from_([1, 2, 3], "km")

>>> vec.uconvert({"length": "km"})
CartesianPos3D(
    x=Quantity(1, unit='km'), y=Quantity(2, unit='km'), z=Quantity(3, unit='km')
)

>>> vec.uconvert(cx.vecs.ToUnitsOptions.consistent)
CartesianPos3D(
    x=Quantity(1, unit='km'), y=Quantity(2, unit='km'), z=Quantity(3, unit='km')
)

>>> usys = u.unitsystem("m", "s", "kg", "rad")

>>> print(vec.uconvert(usys))
<CartesianPos3D: (x, y, z) [m]
    [1000. 2000. 3000.]>

>>> print(vec.uconvert("galactic"))
<CartesianPos3D: (x, y, z) [kpc]
    [3.241e-17 6.482e-17 9.722e-17]>

Parameters:

• args (Any)

• kw (Any)

Return type:

Any

property units: MappingProxyType

Get the units of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.units
mappingproxy({'x': Unit("km"), 'y': Unit("km"), 'z': Unit("km")})

vconvert(target: type, *args: Any, **kwargs: Any)

Represent the vector as another type.

This just forwards to coordinax.vconvert.

Parameters:

• target (type[coordinax.AbstractVectorLike]) – The type to represent the vector as.

• *args (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

• **kwargs (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

• self (AbstractVectorLike)

Return type:

AbstractVectorLike

Examples

>>> import unxt as u
>>> import coordinax.vecs as cxv

Transforming a Position:

>>> q_cart = cxv.CartesianPos3D.from_([1, 2, 3], "m")

>>> q_sph = q_cart.vconvert(cxv.SphericalPos)
>>> print(q_sph)
<SphericalPos: (r[m], theta[rad], phi[rad])
    [3.742 0.641 1.107]>

>>> q_ps = q_cart.vconvert(cxv.ProlateSpheroidalPos, Delta=u.Quantity(1.5, "m"))
>>> print(q_ps)
<ProlateSpheroidalPos: (mu[m2], nu[m2], phi[rad])
 Delta=Quantity(1.5, unit='m')
    [14.89   1.36   1.107]>

>>> print((q_ps.vconvert(cxv.CartesianPos3D) - q_cart).round(3))
<CartesianPos3D: (x, y, z) [m]
    [-0.  0.  0.]>

Transforming a Velocity:

>>> v_cart = cxv.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> v_sph = v_cart.vconvert(cxv.SphericalVel, q_cart)
>>> print(v_sph)
<SphericalVel: (r[m / s], theta[rad / s], phi[rad / s])
    [ 3.742e+00 -8.941e-08  0.000e+00]>

Transforming an Acceleration:

>>> a_cart = cxv.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> a_sph = a_cart.vconvert(cxv.SphericalAcc, v_cart, q_cart)
>>> print(a_sph)
<SphericalAcc: (r[m / s2], theta[rad / s2], phi[rad / s2])
    [13.363  0.767 -1.2  ]>

vconvert(self: AbstractVectorLike, target: type, *args: Any, **kwargs: Any) → AbstractVectorLike

Parameters:

• self (AbstractVectorLike)

• target (type)

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Represent the vector as another type, forwarding to coordinax.vconvert.

Examples

>>> import unxt as u
>>> import coordinax.vecs as cxv

Transforming a Position:

>>> q_cart = cxv.CartesianPos3D.from_([1, 2, 3], "m")

>>> q_sph = q_cart.vconvert(cxv.SphericalPos)
>>> print(q_sph)
<SphericalPos: (r[m], theta[rad], phi[rad])
    [3.742 0.641 1.107]>

>>> q_ps = q_cart.vconvert(cxv.ProlateSpheroidalPos, Delta=u.Quantity(1.5, "m"))
>>> print(q_ps)
<ProlateSpheroidalPos: (mu[m2], nu[m2], phi[rad])
    Delta=Quantity(1.5, unit='m')
    [14.89   1.36   1.107]>

>>> print((q_ps.vconvert(cxv.CartesianPos3D) - q_cart).round(3))
<CartesianPos3D: (x, y, z) [m]
    [-0.  0.  0.]>

Transforming a Velocity:

>>> v_cart = cxv.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> v_sph = v_cart.vconvert(cxv.SphericalVel, q_cart)
>>> print(v_sph)
<SphericalVel: (r[m / s], theta[rad / s], phi[rad / s])
    [ 3.742e+00 -8.941e-08  0.000e+00]>

Transforming an Acceleration:

>>> a_cart = cxv.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> a_sph = a_cart.vconvert(cxv.SphericalAcc, v_cart, q_cart)
>>> print(a_sph)
<SphericalAcc: (r[m / s2], theta[rad / s2], phi[rad / s2])
    [13.363  0.767 -1.2  ]>

Parameters:

• self (AbstractVectorLike)

• target (type)

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

data: AbstractVar[KinematicSpace]

The data of the coordinate. This is a coordinax.KinematicSpace object, which is a collection of vectors.

frame: AbstractVar[AbstractReferenceFrame]

The reference frame of the coordinate as a coordinax.frames.AbstractReferenceFrame object.

class coordinax.frames.Coordinate(data: ArgT | PassThroughTs, frame: ArgT | PassThroughTs)

Bases: AbstractCoordinate

Coordinates are vectors in a reference frame.

Examples

>>> import coordinax as cx

>>> coord = cx.Coordinate(cx.CartesianPos3D.from_([1, 2, 3], "kpc"),
...                       cx.frames.ICRS())
>>> coord
Coordinate(
    KinematicSpace({ 'length': CartesianPos3D( ... ) }),
    frame=ICRS()
)

Alternative Construction:

>>> frame = cx.frames.ICRS()
>>> data = cx.CartesianPos3D.from_([1, 2, 3], "kpc")
>>> cx.Coordinate.from_({"data": data, "frame": frame})
Coordinate(
    KinematicSpace({ 'length': CartesianPos3D( ... ) }),
    frame=ICRS()
)

Changing Representation:

>>> frame = cx.frames.ICRS()
>>> data = cx.CartesianPos3D.from_([1, 2, 3], "kpc")
>>> coord = cx.Coordinate(data, frame)

>>> coord.vconvert(cx.SphericalPos)
Coordinate(
    KinematicSpace({ 'length': SphericalPos( ... ) }),
    frame=ICRS()
)

Showing Frame Transformation:

>>> space = cx.KinematicSpace(
...     length=cx.CartesianPos3D.from_([1.0, 0, 0], "pc"),
...     speed=cx.CartesianVel3D.from_([1.0, 0, 0], "km/s"))

>>> w=cx.Coordinate(
...     data=space,
...     frame=cx.frames.TransformedReferenceFrame(
...         cx.frames.Galactocentric(),
...         cx.ops.GalileanSpatialTranslation.from_([20, 0, 0], "kpc"),
...     ),
... )

>>> w.to_frame(cx.frames.ICRS())
Coordinate(
    KinematicSpace({
        'length': CartesianPos3D(...), 'speed': CartesianVel3D(...) }),
    frame=ICRS()
)

>>> w.to_frame(cx.frames.ICRS()).data["length"]
CartesianPos3D(
  x=Quantity(-1587.6683, unit='pc'),
  y=Quantity(-24573.762, unit='pc'),
  z=Quantity(-13583.504, unit='pc')
)

Parameters:

• data (Union[TypeVar(ArgT), TypeVar(PassThroughTs)])

• frame (Union[TypeVar(ArgT), TypeVar(PassThroughTs)])

property T: Self

Transpose the vector.

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can transpose a vector:

>>> vec = cx.CartesianPos3D(x=u.Quantity([[0, 1], [2, 3]], "m"),
...                         y=u.Quantity([[0, 1], [2, 3]], "m"),
...                         z=u.Quantity([[0, 1], [2, 3]], "m"))
>>> vec.T.x
Quantity(Array([[0, 2],
                          [1, 3]], dtype=int32), unit='m')

asdict(*, dict_factory: ~collections.abc.Callable[[~typing.Any], ~collections.abc.Mapping[str, ~unxt._src.quantity.base.AbstractQuantity]] = <class 'dict'>)

Return the vector as a Mapping.

Parameters:

dict_factory (Callable[[Any], Mapping[str, AbstractQuantity]]) – The type of the mapping to return.

Returns:

The vector as a mapping.

Return type:

Mapping[str, Quantity]

See also

None

This applies recursively to the components of the vector.

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can get the vector as a mapping:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.asdict()
{'x': Quantity(Array([[1, 2], [3, 4]], dtype=int32), unit='m'),
 'y': Quantity(Array(0, dtype=int32, ...), unit='m')}

astype(dtype: Any, /, **kwargs: Any)

Cast the vector to a new dtype.

Parameters:

• dtype (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

components = ('data', 'frame')

copy()

Return a copy of the vector.

Return type:

Self

Examples

>>> import coordinax as cx

>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> print(vec.copy())
<CartesianPos3D: (x, y, z) [m]
    [1 2 3]>

property devices: MappingProxyType

Get the devices of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.devices
mappingproxy({'x': CpuDevice(id=0), 'y': CpuDevice(id=0),
              'z': CpuDevice(id=0)})

property dtype

property dtypes: MappingProxyType

Get the dtypes of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.dtypes
mappingproxy({'x': dtype('int32'), 'y': dtype('int32'),
              'z': dtype('int32')})

flatten()

Flatten the vector.

Return type:

Self

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.shape
(2, 2)

>>> vec.flatten().shape
(4,)

classmethod from_(cls: type[AbstractVectorLike], *args: Any, **kwargs: Any)

Create a vector-like object from arguments.

Examples

>>> import coordinax.vecs as cxv

>>> q = cxv.CartesianPos3D.from_([1, 2, 3], "m")
>>> print(q)
<CartesianPos3D: (x, y, z) [m]
    [1 2 3]>

>>> v = cxv.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> print(v)
<CartesianVel3D: (x, y, z) [m / s]
    [1 2 3]>

>>> space = cxv.KinematicSpace.from_(q)
>>> print(space)
KinematicSpace({
 'length': <CartesianPos3D: (x, y, z) [m]
               [1 2 3]>
})

from_(cls: type[AbstractVector], *args: Any, **kwargs: Any) → AbstractVector

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Create a vector from arguments.

See coordinax.vector for more information.

from_(cls: type[KinematicSpace], obj: KinematicSpace, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a Space, returning the KinematicSpace.

Examples

>>> import coordinax as cx

>>> q = cx.KinematicSpace.from_(cx.CartesianPos3D.from_([1, 2, 3], "m"))
>>> cx.KinematicSpace.from_(q) is q
True

from_(cls: type[KinematicSpace], obj: AbstractPos, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a coordinax.KinematicSpace from a coordinax.AbstractPos.

Examples

>>> import coordinax as cx

>>> q = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> w = cx.KinematicSpace.from_(q)
>>> w
KinematicSpace({ 'length': CartesianPos3D( ... ) })

from_(cls: type[KinematicSpace], q: AbstractPos, p: AbstractVel, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a coordinax.KinematicSpace from a coordinax.AbstractPos.

Examples

>>> import coordinax as cx

>>> q = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> p = cx.CartesianVel3D.from_([4, 5, 6], "m/s")
>>> w = cx.KinematicSpace.from_(q, p)
>>> w
KinematicSpace({ 'length': CartesianPos3D( ... ), 'speed': CartesianVel3D( ... ) })

from_(cls: type[KinematicSpace], q: AbstractPos, p: AbstractVel, a: AbstractAcc, /) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a coordinax.KinematicSpace from a coordinax.AbstractPos.

Examples

>>> import coordinax as cx

>>> q = cx.vecs.CartesianPos3D.from_([1, 2, 3], "m")
>>> p = cx.vecs.CartesianVel3D.from_([4, 5, 6], "m/s")
>>> a = cx.vecs.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> w = cx.KinematicSpace.from_(q, p, a)
>>> w
KinematicSpace({ 'length': CartesianPos3D( ... ),
        'speed': CartesianVel3D( ... ),
        'acceleration': CartesianAcc3D( ... ) })

from_(cls: type[KinematicSpace], obj: Mapping[str, Any]) → KinematicSpace

Parameters:

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Construct a KinematicSpace from a Mapping.

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> space = cx.KinematicSpace.from_({ 'length': u.Quantity([1, 2, 3], "m") })
>>> print(space)
KinematicSpace({
   'length': <CartesianPos3D: (x, y, z) [m]
       [1 2 3]>
})

Parameters:

• cls (type[AbstractVectorLike])

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

property mT: Self

Transpose the vector.

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can transpose a vector:

>>> vec = cx.CartesianPos3D(x=u.Quantity([[0, 1], [2, 3]], "m"),
...                         y=u.Quantity([[0, 1], [2, 3]], "m"),
...                         z=u.Quantity([[0, 1], [2, 3]], "m"))
>>> vec.mT.x
Quantity(Array([[0, 2],
                          [1, 3]], dtype=int32), unit='m')

property ndim: int

Number of array dimensions (axes).

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can get the number of dimensions of a vector:

>>> vec = cx.vecs.CartesianPos2D.from_([1, 2], "m")
>>> vec.ndim
0

>>> vec = cx.vecs.CartesianPos2D.from_([[1, 2], [3, 4]], "m")
>>> vec.ndim
1

ndim is calculated from the broadcasted shape. We can see this by creating a 2D vector in which the components have different shapes:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.ndim
2

ravel()

Ravel the vector.

Return type:

Self

Examples

>>> import unxt as u
>>> import coordinax as cx

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.shape
(2, 2)

>>> vec.ravel().shape
(4,)

represent_as(target: type, *args: Any, **kwargs: Any)

Represent the vector as another type.

This just forwards to coordinax.vconvert.

Parameters:

• target (type[coordinax.AbstractVel]) – The type to represent the vector as.

• *args (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

• **kwargs (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

Return type:

Any

Examples

>>> import coordinax as cx

Transforming a Position:

>>> q_cart = cx.CartesianPos3D.from_([1, 2, 3], "m")
>>> q_sph = q_cart.represent_as(cx.SphericalPos)
>>> q_sph
SphericalPos( ... )
>>> q_sph.r
Distance(Array(3.7416575, dtype=float32), unit='m')

Transforming a Velocity:

>>> v_cart = cx.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> v_sph = v_cart.represent_as(cx.SphericalVel, q_cart)
>>> v_sph
SphericalVel( ... )

Transforming an Acceleration:

>>> a_cart = cx.vecs.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> a_sph = a_cart.represent_as(cx.vecs.SphericalAcc, v_cart, q_cart)
>>> print(a_sph)
<SphericalAcc: (r[m / s2], theta[rad / s2], phi[rad / s2])
    [13.363  0.767 -1.2  ]>

reshape(*shape: Any, order: str = 'C')

Reshape the components of the vector.

Parameters:

• *shape (Any) – The new shape.

• order (str) – The order to use for the reshape.

Return type:

Self

Examples

We assume the following imports:

>>> import unxt as u
>>> import coordinax as cx

We can reshape a vector:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))

>>> vec.reshape(4)
CartesianPos2D(x=Quantity([1, 2, 3, 4], unit='m'),
               y=Quantity([0, 0, 0, 0], unit='m'))

round(decimals: int = 0)

Round the components of the vector.

Parameters:

decimals (int) – The number of decimals to round to.

Return type:

Self

Examples

>>> import unxt as u
>>> import coordinax as cx

We can round a vector:

>>> vec = cx.vecs.CartesianPos2D.from_([[1.1, 2.2], [3.3, 4.4]], "m")
>>> vec.round(0)
CartesianPos2D(x=Quantity([1., 3.], unit='m'), y=Quantity([2., 4.], unit='m'))

property shape: tuple[int, ...]

Return the shape of the vector.

Examples

>>> import unxt as u
>>> import coordinax as cx

We can get the shape of a vector:

>>> vec = cx.vecs.CartesianPos1D(x=u.Quantity([1, 2], "m"))
>>> vec.shape
(2,)

>>> vec = cx.vecs.CartesianPos1D(x=u.Quantity([[1, 2], [3, 4]], "m"))
>>> vec.shape
(2, 2)

shape is calculated from the broadcasted shape. We can see this by creating a 2D vector in which the components have different shapes:

>>> vec = cx.vecs.CartesianPos2D(x=u.Quantity([[1, 2], [3, 4]], "m"),
...                              y=u.Quantity(0, "m"))
>>> vec.shape
(2, 2)

>>> space = cx.KinematicSpace(length=vec)
>>> space.shape
(2, 2)

property shapes: MappingProxyType

Get the shapes of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.shapes
mappingproxy({'x': (), 'y': (), 'z': ()})

property size

property sizes: MappingProxyType

Get the sizes of the vector’s components.

Examples

>>> import coordinax as cx

>>> cx.vecs.CartesianPos2D.from_([1, 2], "m").sizes
mappingproxy({'x': 1, 'y': 1})

>>> cx.vecs.CartesianPos2D.from_([[1, 2], [1, 2]], "m").sizes
mappingproxy({'x': 2, 'y': 2})

to_device(device: None | Device = None)

Move the vector to a new device.

Examples

>>> from jax import devices
>>> import unxt as u
>>> import coordinax as cx

We can move a vector to a new device:

>>> vec = cx.vecs.CartesianPos1D(u.Quantity([1, 2], "m"))
>>> vec.to_device(devices()[0])
CartesianPos1D(x=Quantity([1, 2], unit='m'))

Parameters:

device (None | Device)

Return type:

Self

to_frame(toframe: AbstractReferenceFrame, /, t: Quantity | None = None)

Transform the coordinate to a specified frame.

Examples

>>> import coordinax as cx

>>> cicrs = cx.Coordinate(cx.CartesianPos3D.from_([1, 2, 3], "kpc"),
...                       cx.frames.ICRS())

>>> cicrs.to_frame(cx.frames.ICRS()) is cicrs
True

>>> cgcf = cicrs.to_frame(cx.frames.Galactocentric())
>>> cgcf
Coordinate(
    KinematicSpace({ 'length': CartesianPos3D( ... ) }),
    frame=Galactocentric( ... )
)

Parameters:

• toframe (AbstractReferenceFrame)

• t (Quantity | None)

Return type:

AbstractCoordinate

uconvert(*args: Any, **kw: Any)

Convert the vector to the given units.

This just forwards to unxt.uconvert, reversing the order of the arguments to match the unxt API.

Examples

>>> import coordinax as cx

>>> vec = cx.vecs.CartesianPos3D.from_([1, 2, 3], "km")

>>> vec.uconvert({"length": "km"})
CartesianPos3D(
    x=Quantity(1, unit='km'), y=Quantity(2, unit='km'), z=Quantity(3, unit='km')
)

>>> vec.uconvert(cx.vecs.ToUnitsOptions.consistent)
CartesianPos3D(
    x=Quantity(1, unit='km'), y=Quantity(2, unit='km'), z=Quantity(3, unit='km')
)

>>> usys = u.unitsystem("m", "s", "kg", "rad")

>>> print(vec.uconvert(usys))
<CartesianPos3D: (x, y, z) [m]
    [1000. 2000. 3000.]>

>>> print(vec.uconvert("galactic"))
<CartesianPos3D: (x, y, z) [kpc]
    [3.241e-17 6.482e-17 9.722e-17]>

Parameters:

• args (Any)

• kw (Any)

Return type:

Any

property units: MappingProxyType

Get the units of the vector’s components.

Examples

>>> import coordinax as cx
>>> vec = cx.CartesianPos3D.from_([1, 2, 3], "km")
>>> vec.units
mappingproxy({'x': Unit("km"), 'y': Unit("km"), 'z': Unit("km")})

vconvert(target: type, *args: Any, **kwargs: Any)

Represent the vector as another type.

This just forwards to coordinax.vconvert.

Parameters:

• target (type[coordinax.AbstractVectorLike]) – The type to represent the vector as.

• *args (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

• **kwargs (Any) – Extra arguments. These are passed to coordinax.vconvert and might be used, depending on the dispatched method. E.g. for transforming an acceleration, generally the first argument is the velocity (coordinax.AbstractVel) followed by the position (coordinax.AbstractPos) at which the acceleration is defined. In general this is a required argument, though it is not for Cartesian-to-Cartesian transforms – see https://en.wikipedia.org/wiki/Tensors_in_curvilinear_coordinates for more information.

• self (AbstractVectorLike)

Return type:

AbstractVectorLike

Examples

>>> import unxt as u
>>> import coordinax.vecs as cxv

Transforming a Position:

>>> q_cart = cxv.CartesianPos3D.from_([1, 2, 3], "m")

>>> q_sph = q_cart.vconvert(cxv.SphericalPos)
>>> print(q_sph)
<SphericalPos: (r[m], theta[rad], phi[rad])
    [3.742 0.641 1.107]>

>>> q_ps = q_cart.vconvert(cxv.ProlateSpheroidalPos, Delta=u.Quantity(1.5, "m"))
>>> print(q_ps)
<ProlateSpheroidalPos: (mu[m2], nu[m2], phi[rad])
 Delta=Quantity(1.5, unit='m')
    [14.89   1.36   1.107]>

>>> print((q_ps.vconvert(cxv.CartesianPos3D) - q_cart).round(3))
<CartesianPos3D: (x, y, z) [m]
    [-0.  0.  0.]>

Transforming a Velocity:

>>> v_cart = cxv.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> v_sph = v_cart.vconvert(cxv.SphericalVel, q_cart)
>>> print(v_sph)
<SphericalVel: (r[m / s], theta[rad / s], phi[rad / s])
    [ 3.742e+00 -8.941e-08  0.000e+00]>

Transforming an Acceleration:

>>> a_cart = cxv.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> a_sph = a_cart.vconvert(cxv.SphericalAcc, v_cart, q_cart)
>>> print(a_sph)
<SphericalAcc: (r[m / s2], theta[rad / s2], phi[rad / s2])
    [13.363  0.767 -1.2  ]>

vconvert(self: AbstractVectorLike, target: type, *args: Any, **kwargs: Any) → AbstractVectorLike

Parameters:

• self (AbstractVectorLike)

• target (type)

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

Represent the vector as another type, forwarding to coordinax.vconvert.

Examples

>>> import unxt as u
>>> import coordinax.vecs as cxv

Transforming a Position:

>>> q_cart = cxv.CartesianPos3D.from_([1, 2, 3], "m")

>>> q_sph = q_cart.vconvert(cxv.SphericalPos)
>>> print(q_sph)
<SphericalPos: (r[m], theta[rad], phi[rad])
    [3.742 0.641 1.107]>

>>> q_ps = q_cart.vconvert(cxv.ProlateSpheroidalPos, Delta=u.Quantity(1.5, "m"))
>>> print(q_ps)
<ProlateSpheroidalPos: (mu[m2], nu[m2], phi[rad])
    Delta=Quantity(1.5, unit='m')
    [14.89   1.36   1.107]>

>>> print((q_ps.vconvert(cxv.CartesianPos3D) - q_cart).round(3))
<CartesianPos3D: (x, y, z) [m]
    [-0.  0.  0.]>

Transforming a Velocity:

>>> v_cart = cxv.CartesianVel3D.from_([1, 2, 3], "m/s")
>>> v_sph = v_cart.vconvert(cxv.SphericalVel, q_cart)
>>> print(v_sph)
<SphericalVel: (r[m / s], theta[rad / s], phi[rad / s])
    [ 3.742e+00 -8.941e-08  0.000e+00]>

Transforming an Acceleration:

>>> a_cart = cxv.CartesianAcc3D.from_([7, 8, 9], "m/s2")
>>> a_sph = a_cart.vconvert(cxv.SphericalAcc, v_cart, q_cart)
>>> print(a_sph)
<SphericalAcc: (r[m / s2], theta[rad / s2], phi[rad / s2])
    [13.363  0.767 -1.2  ]>

Parameters:

• self (AbstractVectorLike)

• target (type)

• args (Any)

• kwargs (Any)

Return type:

AbstractVectorLike

data: KinematicSpace

The data of the coordinate. This is a coordinax.KinematicSpace object, which is a collection of vectors.

frame: AbstractReferenceFrame

The reference frame of the coordinate as a coordinax.frames.AbstractReferenceFrame object. This can be from a reference frame object, or any input that can construct a coordinax.frames.TransformedReferenceFrame via coordinax.frames.AbstractReferenceFrame.from_.

class coordinax.frames.AbstractSpaceFrame

Bases: AbstractReferenceFrame

ABC for space-related reference frames.

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

class coordinax.frames.ICRS

Bases: AbstractSpaceFrame

The International Celestial Reference System (ICRS).

Examples

>>> import coordinax as cx
>>> frame = cx.frames.ICRS()
>>> frame
ICRS()

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

class coordinax.frames.Galactocentric(galcen: ~typing.Any = <factory>, roll: ~dataclassish._src.converters.ArgT | ~dataclassish._src.converters.PassThroughTs = Quantity(Array(0, dtype=int32, weak_type=True), unit='deg'), z_sun: ~typing.Any = Quantity(Array(20.8, dtype=float32, weak_type=True), unit='pc'), galcen_v_sun: ~typing.Any = <factory>)

Bases: AbstractSpaceFrame

Reference frame centered at the Galactic center.

Based on the Astropy implementation of the Galactocentric frame.

Examples

>>> import coordinax as cx
>>> frame = cx.frames.Galactocentric()
>>> frame
Galactocentric(
  galcen=LonLatSphericalPos( ... ),
  roll=Quantity(weak_i32[], unit='deg'),
  z_sun=Quantity(weak_f32[], unit='pc'),
  galcen_v_sun=CartesianVel3D( ... )
)

Parameters:

• galcen (Any)

• roll (Union[TypeVar(ArgT), TypeVar(PassThroughTs)])

• z_sun (Any)

• galcen_v_sun (Any)

classmethod from_(cls: type[AbstractReferenceFrame], obj: Any, /)

Construct a reference frame.

from_(cls: type[AbstractReferenceFrame], obj: Mapping[str, Any], /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from a mapping.

Examples

>>> import coordinax.frames as cxf

>>> icrs = cxf.ICRS.from_({})
>>> icrs
ICRS()

>>> gcf = cxf.Galactocentric.from_({})
>>> print(gcf)
Galactocentric( ... )

from_(cls: type[AbstractReferenceFrame], obj: AbstractReferenceFrame, /) → AbstractReferenceFrame

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct a reference frame from another reference frame.

Raises:

TypeError – If the input object is not a subclass of the target class.

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> cxf.AbstractReferenceFrame.from_(alice) is alice
True

>>> try:
...     cxf.Galactocentric.from_(alice)
... except TypeError as e:
...     print(e)
Cannot construct 'Galactocentric' from Alice()

from_(cls: type[ICRS], obj: ICRS, /) → ICRS

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.ICRS.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_icrs = apyc.ICRS()
>>> cxf.ICRS.from_(apy_icrs)
ICRS()

from_(cls: type[Galactocentric], obj: Galactocentric, /) → Galactocentric

Parameters:

obj (Any)

Return type:

AbstractReferenceFrame

Construct from a astropy.coordinates.Galactocentric.

Examples

>>> import astropy.coordinates as apyc
>>> import coordinax.frames as cxf

>>> apy_gcf = apyc.Galactocentric()
>>> apy_gcf
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
(266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>

>>> gcf = cxf.Galactocentric.from_(apy_gcf)
>>> gcf
Galactocentric(
    galcen=LonLatSphericalPos( ... ),
    roll=Quantity(f32[], unit='deg'),
    z_sun=Quantity(f32[], unit='pc'),
    galcen_v_sun=CartesianVel3D( ... )
)

Checking equality

>>> (gcf.galcen.lon.ustrip("deg") == apy_gcf.galcen_coord.ra.to_value("deg")
...  and gcf.galcen.lat.ustrip("deg") == apy_gcf.galcen_coord.dec.to_value("deg")
...  and gcf.galcen.distance.ustrip("kpc") == apy_gcf.galcen_distance.to_value("kpc") )
Array(True, dtype=bool)

Parameters:

• cls (type[AbstractReferenceFrame])

• obj (Any)

Return type:

AbstractReferenceFrame

roll: Union[Shaped[Quantity[PhysicalType('angle')], ''], Shaped[Angle, '']] = Quantity(Array(0, dtype=int32, weak_type=True), unit='deg')

Rotation angle of the Galactic center from the ICRS x-axis.

roll0: ClassVar[Union[Shaped[Quantity[PhysicalType('angle')], ''], Shaped[Angle, '']]] = Quantity(Array(58.598633, dtype=float32, weak_type=True), unit='deg')

The angle between the Galactic center and the ICRS x-axis.

transform_op(to_frame: AbstractReferenceFrame, /)

Make a frame transform operator.

Parameters:

to_frame (AbstractReferenceFrame) – The reference frame to transform to.

Returns:

The operator that transforms coordinates from this frame to to_frame.

Return type:

AbstractOperator

Examples

>>> import coordinax.frames as cxf

>>> alice = cxf.Alice()
>>> bob = cxf.Bob()
>>> op = alice.transform_op(bob)
>>> op
Pipe(( ... ))

>>> op = bob.transform_op(alice)
>>> op
Pipe(( ... ))

z_sun: Quantity[PhysicalType('length')] = Quantity(Array(20.8, dtype=float32, weak_type=True), unit='pc')

Distance from the Sun to the Galactic center. https://ui.adsabs.harvard.edu/abs/2019MNRAS.482.1417B

galcen: LonLatSphericalPos

RA, Dec, and distance of the Galactic center from an ICRS origin. ra, dec: https://ui.adsabs.harvard.edu/abs/2004ApJ…616..872R distance: https://ui.adsabs.harvard.edu/abs/2018A%26A…615L..15G

galcen_v_sun: CartesianVel3D

Velocity of the Sun in the Galactic center frame. https://ui.adsabs.harvard.edu/abs/2018RNAAS…2..210D https://ui.adsabs.harvard.edu/abs/2018A%26A…615L..15G https://ui.adsabs.harvard.edu/abs/2004ApJ…616..872R