.. _utils-iers:
***************************************
IERS data access (`astropy.utils.iers`)
***************************************
Introduction
============
The `~astropy.utils.iers` package provides access to the tables provided by the
`International Earth Rotation and Reference Systems `_
(IERS) service, in particular the `Earth Orientation data
`_
allowing interpolation of published UT1-UTC and polar motion values for given
times. The UT1-UTC values are used in :ref:`astropy-time` to provide UT1 values, and
the polar motions are used in `astropy.coordinates` to determine Earth
orientation for celestial-to-terrestrial coordinate transformations.
.. note:: The package also provides machinery to track leap seconds. Since it
generally should not be necessary to deal with those by hand, this
is not discussed below. For details, see the documentation of
`~astropy.utils.iers.LeapSeconds`.
There are two IERS data products that we discuss here:
- **Bulletin A** (:class:`~astropy.utils.iers.IERS_A`) is updated weekly and has
historical data starting from 1973 and predictive data for 1 year into the
future. It contains Earth orientation parameters x/y pole, UT1-UTC and their
errors at daily intervals. This data file needs to be download from an IERS
data service or mirror.
- **Bulletin B** (:class:`~astropy.utils.iers.IERS_B`) is updated monthly and
has data from 1962 up to the time when it is generated. This file contains
Earth's orientation in the IERS Reference System including Universal Time,
coordinates of the terrestrial pole, and celestial pole offsets. The last
available IERS-B file just prior to each ``astropy`` release is included in
the ``astropy`` package.
Getting started
===============
By default the latest IERS-A values (which include approximately
one year of predictive values) are automatically downloaded from the IERS
service when required. This happens when a time or coordinate transformation
needs a value which is not already available via the download cache. In most
cases there is no need for invoking the `~astropy.utils.iers` classes oneself,
but it is useful to understand the situations when a download will occur
and how this can be controlled.
Basic usage
-----------
By default, the IERS data are managed via instances of the
:class:`~astropy.utils.iers.IERS_Auto` class. These instances are created
internally within the relevant time and coordinate objects during
transformations. If the astropy data cache does not have the required IERS
data file then astropy will request the file from the IERS service. This will
occur the first time such a transform is done for a new setup or on a new
machine. Here is an example that shows the typical download progress bar::
>>> from astropy.time import Time
>>> t = Time('2016:001')
>>> t.ut1 # doctest: +SKIP
Downloading https://maia.usno.navy.mil/ser7/finals2000A.all
|==================================================================| 3.0M/3.0M (100.00%) 6s