Skip to main content
`Ctrl`+`K`

# Galactocentric

class astropy.coordinates.Galactocentric(*args, **kwargs)

  Bases: `BaseCoordinateFrame`

  A coordinate or frame in the Galactocentric system.

  This frame allows specifying the Sun-Galactic center distance, the height of the Sun above the Galactic midplane, and the solar motion relative to the Galactic center. However, as there is no modern standard definition of a Galactocentric reference frame, it is important to pay attention to the default values used in this class if precision is important in your code. The default values of the parameters of this frame are taken from the original definition of the frame in 2014. As such, the defaults are somewhat out of date relative to recent measurements made possible by, e.g., Gaia. The defaults can, however, be changed at runtime by setting the parameter set name in `galactocentric_frame_defaults`.

  The current default parameter set is `"pre-v4.0"`, indicating that the parameters were adopted before `astropy` version 4.0. A regularly-updated parameter set can instead be used by setting `galactocentric_frame_defaults.set ('latest')`, and other parameter set names may be added in future versions. To find out the scientific papers that the current default parameters are derived from, use `galcen.frame_attribute_references` (where `galcen` is an instance of this frame), which will update even if the default parameter set is changed.

  The position of the Sun is assumed to be on the x axis of the final, right-handed system. That is, the x axis points from the position of the Sun projected to the Galactic midplane to the Galactic center – roughly towards \((l,b) = (0^\circ,0^\circ)\). For the default transformation (\({\rm roll}=0^\circ\)), the y axis points roughly towards Galactic longitude \(l=90^\circ\), and the z axis points roughly towards the North Galactic Pole (\(b=90^\circ\)).

  For a more detailed look at the math behind this transformation, see the document Description of the Galactocentric Coordinate Frame.

  The frame attributes are listed under Other Parameters.

  Parameters:
    data `BaseRepresentation` subclass instance

      A representation object or `None` to have no data (or use the coordinate component arguments, see below).

    x `Quantity`, optional

      Cartesian, Galactocentric \(x\) position component.

    y `Quantity`, optional

      Cartesian, Galactocentric \(y\) position component.

    z `Quantity`, optional

      Cartesian, Galactocentric \(z\) position component.

    v_x `Quantity`, optional

      Cartesian, Galactocentric \(v_x\) velocity component.

    v_y `Quantity`, optional

      Cartesian, Galactocentric \(v_y\) velocity component.

    v_z `Quantity`, optional

      Cartesian, Galactocentric \(v_z\) velocity component.

    representation_type `BaseRepresentation` subclass, `python:str`, optional

      A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing `representation_type='cartesian'` will make the classes expect position data with cartesian names, i.e. `x, y, z` in most cases unless overridden via `frame_specific_representation_info`. To see this frame’s names, check out `<this frame>().representation_info`.

    differential_type `BaseDifferential` subclass, `python:str`, `python:dict`, optional

      A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing `differential_type='cartesian'` will make the classes expect velocity data with the argument names `v_x, v_y, v_z` unless overridden via `frame_specific_representation_info`. To see this frame’s names, check out `<this frame>().representation_info`.

    copy bool, optional

      If `True` (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

  Other Parameters:
    galcen_coord `ICRS`, optional, keyword-only

      The ICRS coordinates of the Galactic center.

    galcen_distance `Quantity`, optional, keyword-only

      The distance from the sun to the Galactic center.

    galcen_v_sun `CartesianRepresentation`, `Quantity` [:ref: ‘speed’], optional, keyword-only

      The velocity of the sun in the Galactocentric frame as Cartesian velocity components.

    z_sun `Quantity` [:ref: ‘length’], optional, keyword-only

      The distance from the sun to the Galactic midplane.

    roll `Angle`, optional, keyword-only

      The angle to rotate about the final x-axis, relative to the orientation for Galactic. For example, if this roll angle is 0, the final x-z plane will align with the Galactic coordinates x-z plane. Unless you really know what this means, you probably should not change this!

    .. versionchanged:: 8.0

      `galcen_v_sun` is now a `CartesianRepresentation` rather than a `CartesianDifferential`.

  Examples

  To transform to the Galactocentric frame with the default frame attributes, pass the uninstantiated class name to the `transform_to()` method of a `SkyCoord` object:

      >>> import astropy.units as u
      >>> import astropy.coordinates as coord
      >>> c = coord.SkyCoord(ra=[158.3122, 24.5] * u.degree,
      ...                    dec=[-17.3, 81.52] * u.degree,
      ...                    distance=[11.5, 24.12] * u.kpc,
      ...                    frame='icrs')
      >>> c.transform_to(coord.Galactocentric)
      <SkyCoord (Galactocentric: 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): (x, y, z) in kpc
          [( -9.43489286, -9.40062188, 6.51345359),
           (-21.11044918, 18.76334013, 7.83175149)]>

  To specify a custom set of parameters, you have to include extra keyword arguments when initializing the Galactocentric frame object:

      >>> c.transform_to(coord.Galactocentric(galcen_distance=8.1*u.kpc))
      <SkyCoord (Galactocentric: galcen_coord=<ICRS Coordinate: (ra, dec) in deg
          (266.4051, -28.936175)>, galcen_distance=8.1 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg): (x, y, z) in kpc
          [( -9.41284763, -9.40062188, 6.51346272),
           (-21.08839478, 18.76334013, 7.83184184)]>

  Similarly, transforming from the Galactocentric frame to another coordinate frame:

      >>> c = coord.SkyCoord(x=[-8.3, 4.5] * u.kpc,
      ...                    y=[0., 81.52] * u.kpc,
      ...                    z=[0.027, 24.12] * u.kpc,
      ...                    frame=coord.Galactocentric)
      >>> c.transform_to(coord.ICRS)
      <SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, kpc)
          [( 88.22423301, 29.88672864,  0.17813456),
           (289.72864549, 49.9865043 , 85.93949064)]>

  Or, with custom specification of the Galactic center:

      >>> c = coord.SkyCoord(x=[-8.0, 4.5] * u.kpc,
      ...                    y=[0., 81.52] * u.kpc,
      ...                    z=[21.0, 24120.0] * u.pc,
      ...                    frame=coord.Galactocentric,
      ...                    z_sun=21 * u.pc, galcen_distance=8. * u.kpc)
      >>> c.transform_to(coord.ICRS)
      <SkyCoord (ICRS): (ra, dec, distance) in (deg, deg, kpc)
          [( 86.2585249 , 28.85773187, 2.75625475e-05),
           (289.77285255, 50.06290457, 8.59216010e+01)]>

  Attributes Summary

  `default_differential` | Default representation for differential data (e.g., velocity)
  `default_representation` | Default representation for position data
  `frame_attributes` |
  `frame_specific_representation_info` | Mapping for frame-specific component names
  `galcen_coord` | The coordinates of the Galactic center
  `galcen_distance` | The distance from the Sun to the Galactic center
  `galcen_v_sun` | The velocity of the Sun in the Galactocentric frame
  `name` |
  `roll` | The rotation angle relative to the orientation for Galactic
  `z_sun` | The distance from the Sun to the Galactic midplane

  Methods Summary

  `get_roll0`() | The additional roll angle (about the final x axis) necessary to align the final z axis to match the Galactic yz-plane.

  Attributes Documentation

  default_differential

    Default representation for differential data (e.g., velocity)

  default_representation

    Default representation for position data

  frame_attributes = {'galcen_coord': <astropy.coordinates.attributes.CoordinateAttribute object>, 'galcen_distance': <astropy.coordinates.attributes.QuantityAttribute object>, 'galcen_v_sun': <astropy.coordinates.attributes.CartesianRepresentationAttribute object>, 'roll': <astropy.coordinates.attributes.QuantityAttribute object>, 'z_sun': <astropy.coordinates.attributes.QuantityAttribute object>}
  frame_specific_representation_info

    Mapping for frame-specific component names

  galcen_coord

    The coordinates of the Galactic center

    No default value

  galcen_distance

    The distance from the Sun to the Galactic center

    No default value

  galcen_v_sun

    The velocity of the Sun in the Galactocentric frame

    No default value

  name = 'galactocentric'
  roll

    The rotation angle relative to the orientation for Galactic

    No default value

  z_sun

    The distance from the Sun to the Galactic midplane

    No default value

  Methods Documentation

  classmethod get_roll0()

    The additional roll angle (about the final x axis) necessary to align the final z axis to match the Galactic yz-plane. Setting the `roll` frame attribute to -this method’s return value removes this rotation, allowing the use of the `Galactocentric` frame in more general contexts.