Skip to main content
`Ctrl`+`K`

# Distance

class astropy.coordinates.Distance(value=None, unit=None, z=None, cosmology=None, distmod=None, parallax=None, dtype=<class 'numpy.inexact'>, copy=True, order=None, subok=False, ndmin=0, allow_negative=False)

  Bases: `SpecificTypeQuantity`

  A one-dimensional distance.

  This can be initialized by providing one of the following:

  - Distance `value` (array or float) and a `unit`

  - |Quantity| object with dimensionality of length

  - Redshift and (optionally) a `Cosmology`

  - Distance modulus

  - Parallax

  Parameters:
    value scalar or `Quantity` [:ref: ‘length’]

      The value of this distance.

    unit `UnitBase` [:ref: ‘length’]

      The unit for this distance.

    z `python:float`

      A redshift for this distance. It will be converted to a distance by computing the luminosity distance for this redshift given the cosmology specified by `cosmology`. Must be given as a keyword argument.

    cosmology `Cosmology` or `python:None`

      A cosmology that will be used to compute the distance from `z`. If `None`, the current cosmology will be used (see `astropy.cosmology` for details).

    distmod `python:float` or `Quantity`

      The distance modulus for this distance. Note that if `unit` is not provided, a guess will be made at the unit between AU, pc, kpc, and Mpc.

    parallax astropy:angle-like

      The parallax in angular units.

    dtype `dtype`, optional

      See `Quantity`.

    copy bool, optional

      See `Quantity`.

    order{‘C’, ‘F’, ‘A’}, optional

      See `Quantity`.

    subok bool, optional

      See `Quantity`.

    ndmin `python:int`, optional

      See `Quantity`.

    allow_negative bool, optional

      Whether to allow negative distances (which are possible in some cosmologies). Default: `False`.

  Raises:
    `UnitsError`

      If the `unit` is not a length unit.

    `ValueError`

      If value specified is less than 0 and `allow_negative=False`.

      If `cosmology` is provided when `z` is not given.

      If either none or more than one of `value`, `z`, `distmod`, or `parallax` were given.

  Examples

      >>> from astropy import units as u
      >>> from astropy.cosmology import WMAP5
      >>> Distance(10, u.Mpc)
      <Distance 10. Mpc>
      >>> Distance(40*u.pc, unit=u.kpc)
      <Distance 0.04 kpc>
      >>> Distance(z=0.23)
      <Distance 1184.01657566 Mpc>
      >>> Distance(z=0.23, cosmology=WMAP5)
      <Distance 1147.78831918 Mpc>
      >>> Distance(distmod=24.47*u.mag)
      <Distance 783.42964277 kpc>
      >>> Distance(parallax=21.34*u.mas)
      <Distance 46.86035614 pc>

  Attributes Summary

  `distmod` | The distance modulus as a `Quantity`.
  `parallax` | The parallax angle as an `Angle` object.
  `z` | Short for `self.compute_z()`.

  Methods Summary

  `compute_z`([cosmology]) | The redshift for this distance assuming its physical distance is a luminosity distance.

  Attributes Documentation

  distmod

    The distance modulus as a `Quantity`.

  parallax

    The parallax angle as an `Angle` object.

  z

    Short for `self.compute_z()`.

  Methods Documentation

  compute_z(cosmology=None, **atzkw)

    The redshift for this distance assuming its physical distance is a luminosity distance.

    Parameters:
      cosmology `Cosmology` or `python:None`

        The cosmology to assume for this calculation, or `None` to use the current cosmology (see `astropy.cosmology` for details).

      **atzkw

        keyword arguments for `z_at_value()`

    Returns:
      z `Quantity`

        The redshift of this distance given the provided `cosmology`.

    Warning

    This method can be slow for large arrays. The redshift is determined using `astropy.cosmology.z_at_value()`, which handles vector inputs (e.g. an array of distances) by element-wise calling of `scipy.optimize.minimize_scalar()`. For faster results consider using an interpolation table; `astropy.cosmology.z_at_value()` provides details.

    See also

    `astropy.cosmology.z_at_value()`

      Find the redshift corresponding to a `astropy.cosmology.FLRW.luminosity_distance()`.