Skip to main content
`Ctrl`+`K`

# Description of the Galactocentric Coordinate Frame

While many other frames implemented in `astropy.coordinates` are standardized in some way (e.g., defined by the IAU), there is no standard Milky Way reference frame with the center of the Milky Way as its origin. (This is distinct from `Galactic` coordinates, which point toward the Galactic Center but have their origin in the Solar System). The `Galactocentric` frame class is meant to be flexible enough to support all common definitions of such a transformation, but with reasonable default parameter values, such as the solar velocity relative to the Galactic center, the solar height above the Galactic midplane, etc. Below, we describe our generalized definition of the transformation from the ICRS to/from Galactocentric coordinates, and describe how to customize the default Galactocentric parameters that are used when the `Galactocentric` frame is initialized without explicitly passing in parameter values.

## Definition of the Transformation

This document describes the mathematics behind the transformation from `ICRS` to `Galactocentric` coordinates. This is described in detail here on account of the mathematical subtleties and the fact that there is no official standard/definition for this frame. For examples of how to use this transformation in code, see the the Examples section of the `Galactocentric` class documentation.

We assume that we start with a 3D position in the ICRS reference frame: a Right Ascension, Declination, and heliocentric distance, \((\alpha, \delta, d)\). We can convert this to a Cartesian position using the standard transformation from Cartesian to spherical coordinates:

\[\begin{split}\begin{aligned} x_{\rm icrs} &= d\cos{\alpha}\cos{\delta}\\ y_{\rm icrs} &= d\sin{\alpha}\cos{\delta}\\ z_{\rm icrs} &= d\sin{\delta}\\ \boldsymbol{r}_{\rm icrs} &= \begin{pmatrix} x_{\rm icrs}\\ y_{\rm icrs}\\ z_{\rm icrs} \end{pmatrix}\end{aligned}\end{split}\]

The first transformation rotates the \(x_{\rm icrs}\) axis so that the new \(x'\) axis points towards the Galactic Center (GC), specified by the ICRS position \((\alpha_{\rm GC}, \delta_{\rm GC})\) (in the `Galactocentric` frame, this is controlled by the frame attribute `galcen_coord`):

\[\begin{split}\begin{aligned} \boldsymbol{R}_1 &= \begin{bmatrix} \cos\delta_{\rm GC}& 0 & \sin\delta_{\rm GC}\\ 0 & 1 & 0 \\ -\sin\delta_{\rm GC}& 0 & \cos\delta_{\rm GC}\end{bmatrix}\\ \boldsymbol{R}_2 &= \begin{bmatrix} \cos\alpha_{\rm GC}& \sin\alpha_{\rm GC}& 0\\ -\sin\alpha_{\rm GC}& \cos\alpha_{\rm GC}& 0\\ 0 & 0 & 1 \end{bmatrix}.\end{aligned}\end{split}\]

The transformation thus far has aligned the \(x'\) axis with the vector pointing from the Sun to the GC, but the \(y'\) and \(z'\) axes point in arbitrary directions. We adopt the orientation of the Galactic plane as the normal to the north pole of Galactic coordinates defined by the IAU (Blaauw et. al. 1960). This extra “roll” angle, \(\eta\), was measured by transforming a grid of points along \(l=0\) to this interim frame and minimizing the square of their \(y'\) positions. We find:

\[\begin{split}\begin{aligned} \eta &= 58.5986320306^\circ\\ \boldsymbol{R}_3 &= \begin{bmatrix} 1 & 0 & 0\\ 0 & \cos\eta & \sin\eta\\ 0 & -\sin\eta & \cos\eta \end{bmatrix}\end{aligned}\end{split}\]

The full rotation matrix thus far is:

\[\begin{split}\begin{gathered} \boldsymbol{R} = \boldsymbol{R}_3 \boldsymbol{R}_1 \boldsymbol{R}_2 = \\ \begin{bmatrix} \cos\alpha_{\rm GC}\cos\delta_{\rm GC}& \cos\delta_{\rm GC}\sin\alpha_{\rm GC}& \sin\delta_{\rm GC}\\ -\cos\alpha_{\rm GC}\sin\delta_{\rm GC}\sin\eta - \sin\alpha_{\rm GC}\cos\eta & -\sin\alpha_{\rm GC}\sin\delta_{\rm GC}\sin\eta + \cos\alpha_{\rm GC}\cos\eta & \cos\delta_{\rm GC}\sin\eta\\ -\cos\alpha_{\rm GC}\sin\delta_{\rm GC}\cos\eta + \sin\alpha_{\rm GC}\sin\eta & -\sin\alpha_{\rm GC}\sin\delta_{\rm GC}\cos\eta - \cos\alpha_{\rm GC}\sin\eta & \cos\delta_{\rm GC}\cos\eta \end{bmatrix}\end{gathered}\end{split}\]

With the rotated position vector \(\boldsymbol{R}\boldsymbol{r}_{\rm icrs}\), we can now subtract the distance to the GC, \(d_{\rm GC}\), which is purely along the \(x'\) axis:

\[\begin{aligned} \boldsymbol{r}' &= \boldsymbol{R}\boldsymbol{r}_{\rm icrs} - d_{\rm GC}\hat{\boldsymbol{x}}_{\rm GC}.\end{aligned}\]

where \(\hat{\boldsymbol{x}}_{\rm GC} = (1,0,0)^{\mathsf{T}}\).

The final transformation accounts for the (specified) height of the Sun above the Galactic midplane by rotating about the final \(y''\) axis by the angle \(\theta= \sin^{-1}(z_\odot / d_{\rm GC})\):

\[\begin{split}\begin{aligned} \boldsymbol{H} &= \begin{bmatrix} \cos\theta & 0 & \sin\theta\\ 0 & 1 & 0\\ -\sin\theta & 0 & \cos\theta \end{bmatrix}\end{aligned}\end{split}\]

where \(z_\odot\) is the measured height of the Sun above the midplane.

The full transformation is then:

\[\boldsymbol{r}_{\rm GC} = \boldsymbol{H} \left( \boldsymbol{R}\boldsymbol{r}_{\rm icrs} - d_{\rm GC}\hat{\boldsymbol{x}}_{\rm GC}\right).\]

Examples:

For an example of how to use the `Galactocentric` frame, see Transforming positions and velocities to and from a Galactocentric frame.

## Controlling the Default Frame Parameters

All of the frame-defining parameters of the `Galactocentric` frame are customizable and can be set by passing arguments in to the `Galactocentric` initializer. However, it is often convenient to use the frame without having to pass in every parameter. Hence, the class comes with reasonable default values for these parameters, but more precise measurements of the solar position or motion in the Galaxy are constantly being made. The default values of the `Galactocentric` frame attributes will therefore be updated as necessary with subsequent releases of `astropy`. We therefore provide a mechanism to globally or locally control the default parameter values used in this frame through the `galactocentric_frame_defaults` `ScienceState` class.

The `galactocentric_frame_defaults` class controls the default parameter settings in `Galactocentric` by mapping a set of string names to particular choices of the parameter values. For an up-to-date list of valid names, see the docstring of `galactocentric_frame_defaults`, but these names are things like `'pre-v4.0'`, which sets the default parameter values to their original definition (i.e. pre-astropy-v4.0) values, and `'v4.0'`, which sets the default parameter values to a more modern set of measurements as updated in Astropy version 4.0. Also, custom sets of measurements can be registered to `galactocentric_frame_defaults` and used like the built-in options.

`galactocentric_frame_defaults` also tracks the references (i.e. scientific papers that define the parameter values) for all parameter values, as well as any further specified metadata information.

As with other `ScienceState` subclasses, the `galactocentric_frame_defaults` class can be used to globally set the frame defaults at runtime.

### Examples

The default parameter values can be seen by initializing the `Galactocentric` frame with no arguments:

    >>> from astropy.coordinates import Galactocentric
    >>> Galactocentric()
    <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)>

These default values can be modified using this class:

    >>> from astropy.coordinates import galactocentric_frame_defaults
    >>> _ = galactocentric_frame_defaults.set('v4.0')
    >>> Galactocentric()
    <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)>
    >>> _ = galactocentric_frame_defaults.set('pre-v4.0')
    >>> Galactocentric()
    <Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
        (266.4051, -28.936175)>, galcen_distance=8.3 kpc, galcen_v_sun=(11.1, 232.24, 7.25) km / s, z_sun=27.0 pc, roll=0.0 deg)>

The default parameters can also be updated by using this class as a context manager to change the default parameter values locally to a piece of your code:

    >>> with galactocentric_frame_defaults.set('pre-v4.0'):
    ...     print(Galactocentric())
    <Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
        (266.4051, -28.936175)>, galcen_distance=8.3 kpc, galcen_v_sun=(11.1, 232.24, 7.25) km / s, z_sun=27.0 pc, roll=0.0 deg)>

Again, changing the default parameter values will not affect frame attributes that are explicitly specified:

    >>> import astropy.units as u
    >>> with galactocentric_frame_defaults.set('pre-v4.0'):
    ...     print(Galactocentric(galcen_distance=8.0*u.kpc))
    <Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
        (266.4051, -28.936175)>, galcen_distance=8.0 kpc, galcen_v_sun=(11.1, 232.24, 7.25) km / s, z_sun=27.0 pc, roll=0.0 deg)>

Additional parameter sets may be registered, for instance to use the Dehnen & Binney (1998) measurements of the solar motion. We can also add metadata, such as the 1-sigma errors:

    >>> state = galactocentric_frame_defaults.get_from_registry("v4.0")
    >>> state["parameters"]["galcen_v_sun"] = (10.00, 225.25, 7.17) * (u.km / u.s)
    >>> state["references"]["galcen_v_sun"] = "http://www.adsabs.harvard.edu/full/1998MNRAS.298..387D"
    >>> state["error"] = {"galcen_v_sun": (0.36, 0.62, 0.38) * (u.km / u.s)}
    >>> galactocentric_frame_defaults.register(name="DB1998", **state)

Just as in the previous examples, the new parameter set can be get / set:

    >>> state = galactocentric_frame_defaults.get_from_registry("DB1998")
    >>> print(state["error"]["galcen_v_sun"])
    [0.36 0.62 0.38] km / s

Unless set with the `galactocentric_frame_defaults` class, the default parameter values for the `Galactocentric` frame are set to `'latest'`, meaning that the default parameter values may change if you update Astropy. If you use the `Galactocentric` frame without specifying all parameter values explicitly, we therefore suggest manually setting the frame default set manually in any science code that depends sensitively on the choice of, e.g., solar motion or the other frame parameters. For example, in such code, we recommend adding something like this to your import block (here using `'v4.0'` as an example):

    >>> import astropy.coordinates as coord
    >>> coord.galactocentric_frame_defaults.set('v4.0')