Coordinate Systems (gala.coordinates)

Introduction

The coordinates subpackage provides functions for converting velocities between various astronomical coordinate frames and systems. This subpackage also provides astropy.coordinates frame classes for coordinate sytems defined by the Sagittarius and Orphan streams.

For the examples below the following imports have already been executed:

>>> import numpy as np
>>> import astropy.coordinates as coord
>>> import astropy.units as u
>>> import gala.coordinates as gc

Getting Started

The core functions in this subpackage provide support to:

  • Convert Galactocentric, cartesian velocities to heliocentric proper motion and radial velocities.
  • Convert proper motions and radial velocities to Galactocentric, cartesian velocities.
  • Convert proper motions from/to ICRS to/from Galactic.
  • Convert radial velocities from/to the Galactic Standard of Rest (GSR) to/from a barycentric frame.

These functions work naturally with the astropy.units and astropy.coordinates subpackages. Handling positional transformations is already supported by astropy.coordinates and new to Astropy v1.0 is a Galactocentric reference frame. However, there is currently no support for transforming velocities in Astropy. The functions below attempt to bridge that gap as a temporary solution until support is added (planned for v1.2).

For example, to convert a spherical, heliocentric velocity (proper motion and radial velocity) in an ICRS frame to a Galactocentric, cartesian velocity, we first have to define an Astropy coordinate to specify the position of the object:

>>> c = coord.SkyCoord(ra=100.68458*u.deg, dec=41.26917*u.deg, distance=1.1*u.kpc)

Then pass this object in to the heliocentric to galactocentric conversion function, vhel_to_gal():

>>> pm = [1.5, -1.7] * u.mas/u.yr
>>> rv = 151.1 * u.km/u.s
>>> gc.vhel_to_gal(c.icrs, pm=pm, rv=rv)
<Quantity [-134.44094022, 228.42957796,  52.97041271] km / s>

Because the input coordinate is given in the ICRS frame, the function assumes that the proper motion is also in this frame, e.g., that the proper motion components are \((\mu_\alpha\cos\delta, \mu_\delta)\). If we instead passed in a coordinate in the Galactic frame, the components are assumed to be \((\mu_l\cos b, \mu_b)\)

>>> gc.vhel_to_gal(c.galactic, pm=pm, rv=rv)
<Quantity [-137.63839042, 232.10966635,  40.73819003] km / s>

The velocity transformation functions allow specifying the circular velocity at the Sun (vcirc) and a 3-vector specifying the Sun’s velocity with respect to the local standard of rest (vlsr). Further customization of the Sun’s location can be made via the Galactocentric frame attributes and passed in with the keyword argument galactocentric_frame

>>> frame = coord.Galactocentric(z_sun=10.*u.pc, galcen_distance=8.3*u.kpc)
>>> gc.vhel_to_gal(c.icrs, pm=pm, rv=rv, galactocentric_frame=frame,
...                vcirc=218*u.km/u.s, vlsr=[0.,0.,0.]*u.km/u.s)
<Quantity [-144.5344455 , 221.17957796,  45.50447318] km / s>

The inverse transformations are also available, with the function vgal_to_hel(). Here, because the input coordinate is passed in after being transformed to the ICRS frame, the output proper motions will also be given in the ICRS frame \((\mu_\alpha\cos\delta, \mu_\delta)\):

>>> xyz = coord.Galactocentric([11., 15, 25] * u.kpc)
>>> vxyz = [121., 150., -75.] * u.km/u.s
>>> pm_ra,pm_dec,vr = gc.vgal_to_hel(xyz.transform_to(coord.ICRS), vxyz)
>>> pm_ra 
<Quantity 0.2834641666390529 mas / yr>
>>> pm_dec 
<Quantity -0.888174413651107 mas / yr>
>>> vr 
<Quantity -29.71790624810498 km / s>

Passing in coordinates in the Galactic frame means that the output proper motions will instead be \((\mu_l\cos b, \mu_b)\)

>>> pm_l,pm_b,vr = gc.vgal_to_hel(xyz.transform_to(coord.Galactic), vxyz)
>>> pm_l 
<Quantity -0.7713637315333076 mas / yr>

All of these functions also work on arrays of coordinates and velocities, e.g.:

>>> xyz = coord.Galactocentric(np.random.uniform(-20,20,size=(3,10)) * u.kpc)
>>> vxyz = np.random.uniform(-150,150,size=(3,10)) * u.km/u.s
>>> gc.vgal_to_hel(xyz.transform_to(coord.ICRS), vxyz) 
...

Using gala.coordinates

More details are provided in the linked pages below:

API

gala.coordinates Package

Functions

cartesian_to_cylindrical(pos, vel) Convert a velocity in Cartesian coordinates to velocity components in cylindrical coordinates.
cartesian_to_physicsspherical(pos, vel) Convert a velocity in Cartesian coordinates to velocity components in spherical coordinates.
cartesian_to_poincare_polar(w) Convert an array of 6D Cartesian positions to Poincaré symplectic polar coordinates.
cartesian_to_spherical(pos, vel) Convert a velocity in Cartesian coordinates to velocity components in spherical coordinates.
cylindrical_to_cartesian(pos, vel) Convert a velocity in Spherical coordinates to Cylindrical coordinates.
physicsspherical_to_cartesian(pos, vel) Convert a velocity in Spherical coordinates to Cartesian coordinates.
pm_gal_to_icrs(coordinate, pm) Convert proper motion in Galactic coordinates (l,b) to ICRS coordinates (RA, Dec).
pm_icrs_to_gal(coordinate, pm) Convert proper motion in ICRS coordinates (RA, Dec) to Galactic coordinates (l,b).
spherical_to_cartesian(pos, vel) Convert a velocity in Spherical coordinates to Cartesian coordinates.
vgal_to_hel(coordinate, vxyz[, vcirc, vlsr, ...]) Convert a Galactocentric, cartesian velocity to a Heliocentric velocity in spherical coordinates (e.g., proper motion and radial velocity).
vgsr_to_vhel(coordinate, vgsr[, vcirc, vlsr]) Convert a radial velocity in the Galactic standard of rest (GSR) to a barycentric radial velocity.
vhel_to_gal(coordinate, pm, rv[, vcirc, ...]) Convert a Heliocentric velocity in spherical coordinates (e.g., proper motion and radial velocity) in the ICRS or Galactic frame to a Galactocentric, cartesian velocity.
vhel_to_vgsr(coordinate, vhel[, vcirc, vlsr]) Convert a velocity from a heliocentric radial velocity to the Galactic standard of rest (GSR).

Classes

Orphan(*args, **kwargs) A Heliocentric spherical coordinate system defined by the orbit of the Orphan stream, as described in Newberg et al.
Quaternion(wxyz) Quaternions for 3D rotations.
Sagittarius(*args, **kwargs) A Heliocentric spherical coordinate system defined by the orbit of the Sagittarius dwarf galaxy, as described in Majewski et al.