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 decribe 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:
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
):
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:
The full rotation matrix thus far is:
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:
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})\):
where \(z_\odot\) is the measured height of the Sun above the midplane.
The full transformation is then:
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.
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)>
Starting with Astropy v4.1, unless set with the
galactocentric_frame_defaults
class, the default
parameter values for the Galactocentric
frame are now 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')