
==========
 Skyfield
==========

.. raw:: html

   <img class="logo" src="_static/logo.png">

.. rst-class:: motto

   *Elegant Astronomy for Python*

Skyfield computes positions for the stars, planets,
and satellites in orbit around the Earth.
Its results should agree
with the positions generated by the United States Naval Observatory
and their *Astronomical Almanac*
to within 0.0005 arcseconds (which equals half a “mas” or milliarcsecond).

* Written in pure Python and installs without any compilation.
* Supports Python 2.6–2.7 and Python 3.3–3.5.
* Has NumPy as its only binary dependency,
  the fundamental package for scientific computing with Python,
  whose vector operations make Skyfield efficient.

Computing the position of Mars in the sky is as easy as:

.. testsetup::

   __import__('skyfield.tests.fixes').tests.fixes.setup()

.. testcode::

    from skyfield.api import load

    planets = load('de421.bsp')
    earth, mars = planets['earth'], planets['mars']

    ts = load.timescale()
    t = ts.now()
    astrometric = earth.at(t).observe(mars)
    ra, dec, distance = astrometric.radec()

    print(ra)
    print(dec)
    print(distance)

.. testoutput::

    10h 47m 56.24s
    +09deg 03' 23.1"
    2.33251 au

Skyfield can compute geocentric coordinates,
as shown in the example above,
or topocentric coordinates specific to your location
on the Earth’s surface:

.. testcode::

    from skyfield.api import Topos

    boston = earth + Topos('42.3583 N', '71.0636 W')
    astrometric = boston.at(t).observe(mars)
    alt, az, d = astrometric.apparent().altaz()

    print(alt)
    print(az)

.. testoutput::

    25deg 27' 54.0"
    101deg 33' 44.0"

Skyfield does not depend on the `AstroPy`_ project
or its compiled libraries.
But it accepts AstroPy time objects as input,
and can return results in native AstroPy units:

.. testcode::

    from astropy import units as u
    xyz = astrometric.position.to(u.au)
    altitude = alt.to(u.deg)

    print(xyz)
    print('{0:0.03f}'.format(altitude))

.. testoutput::

    [-2.19049548  0.71236701  0.36712443] AU
    25.465 deg

Documenation
============

Skyfield’s documentation lives here at the main Skyfield web site:

* :doc:`toc`
* :doc:`installation`
* :doc:`api`
* :ref:`changelog`

But the source code and issue tracker live on other web sites:

* `Skyfield on the Python Package Index <https://pypi.python.org/pypi/skyfield>`_

* `GitHub project page <https://github.com/brandon-rhodes/python-skyfield/>`_

* `GitHub issue tracker <https://github.com/brandon-rhodes/python-skyfield/issues>`_

Most recent release: Version 1.3 on 2018 April 15
=================================================

* Geocentric coordinates now have a
  :meth:`~skyfield.positionlib.Geocentric.subpoint()`
  method that computes the latitude and longitude
  of the point beneath that body.

* All of the ``Timescale`` time constructor methods now accept arrays.

* Emergency fix to stop Skyfield
  from endlessly downloading new copies of ``deltat.preds``,
  since the file has gone out of date at the USNO site.

* Fixed ability of a :class:`~skyfield.starlib.Star`
  to be initialized with a tuple that breaks units into minutes and seconds
  (broke in version 1.2).

* Issues fixed:
  `#170 <https://github.com/skyfielders/python-skyfield/issues/170>`_
  `#172 <https://github.com/skyfielders/python-skyfield/issues/172>`_

See the :ref:`changelog` for all previous versions!

.. testcleanup::

   __import__('skyfield.tests.fixes').tests.fixes.teardown()

.. _astropy: http://docs.astropy.org/en/stable/
