Skip to main content
`Ctrl`+`K`

# galactocentric_frame_defaults

class astropy.coordinates.galactocentric_frame_defaults

  Bases: `ScienceState`

  Global setting of default values for the frame attributes in the `Galactocentric` frame.

  These constancts may be updated in future versions of `astropy`. Note that when using `Galactocentric`, changing values here will not affect any attributes that are set explicitly by passing values in to the `Galactocentric` initializer. Modifying these defaults will only affect the frame attribute values when using the frame as, e.g., `Galactocentric` or `Galactocentric()` with no explicit arguments.

  This class controls the parameter settings by specifying a string name, with the following pre-specified options:

  - ‘pre-v4.0’: The current default value, which sets the default frame attribute values to their original (pre-astropy-v4.0) values.

  - ‘v4.0’: The attribute values as updated in Astropy version 4.0.

  - ‘latest’: An alias of the most recent parameter set (currently: ‘v4.0’)

  Alternatively, user-defined parameter settings may be registered, with `register()`, and used identically as pre-specified parameter sets. At minimum, registrations must have unique names and a dictionary of parameters with keys “galcen_coord”, “galcen_distance”, “galcen_v_sun”, “z_sun”, “roll”. See examples below.

  This class also tracks the references for all parameter values in the attribute `references`, as well as any further information the registry. The pre-specified options can be extended to include similar state information as user-defined parameter settings – for example, to add parameter uncertainties.

  The preferred method for getting a parameter set and metadata, by name, is `get_from_registry()` since it ensures the immutability of the registry.

  See Controlling the Default Frame Parameters for more information.

  Examples

  The default `Galactocentric` frame parameters can be modified globally:

      >>> 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:

      >>> 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. In this example we will modify the required key “parameters”, change the recommended key “references” to match “parameters”, and add the extra key “error” (any key can be added):

      >>> 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"] = "https://ui.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 retrieved with:

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

  Attributes Summary

  `parameters` |
  `references` |

  Methods Summary

  `get_from_registry`(name) | Return Galactocentric solar parameters and metadata given string names for the parameter sets.
  `register`(name, parameters[, references]) | Register a set of parameters.
  `validate`(value) | Validate the value and convert it to its native type, if necessary.

  Attributes Documentation

  parameters
  references

  Methods Documentation

  classmethod get_from_registry(name)

    Return Galactocentric solar parameters and metadata given string names for the parameter sets. This method ensures the returned state is a mutable copy, so any changes made do not affect the registry state.

    Returns:
      state `python:dict`

        Copy of the registry for the string name. Should contain, at minimum:

        - “parameters”: dict

            Galactocentric solar parameters

        - “references”Dict[str, Union[str, Sequence[str]]]

            References for “parameters”. Fields are str or sequence of str.

    Raises:
      `KeyError`

        If invalid string input to registry to retrieve solar parameters for Galactocentric frame.

  classmethod register(name, parameters, references=None, **meta)

    Register a set of parameters.

    Parameters:
      name `python:str`

        The registration name for the parameter and metadata set.

      parameters `python:dict`

        The solar parameters for Galactocentric frame.

      references `python:dict` or `python:None`, optional

        References for contents of `parameters`. None becomes empty dict.

      **meta `python:dict`, optional

        Any other properties to register.

  classmethod validate(value)

    Validate the value and convert it to its native type, if necessary.