
===============
 API Reference
===============

Quick links to the sections below:

.. contents:: :local:

Opening files
=============

.. currentmodule:: skyfield.iokit

::

    # File you already have.

    from skyfield.api import load_file
    planets = load_file('~/Downloads/de405.bsp')

.. autosummary::

   load_file

::

    # File you want Skyfield to download automatically.

    from skyfield.api import load
    ts = load.timescale()
    planets = load('de405.bsp')

.. autosummary::

   Loader
   Loader.build_url
   Loader.path_to
   Loader.timescale
   Loader.tle_file

Time scales
===========

.. currentmodule:: skyfield.timelib

A Skyfield `Timescale` object is typically built
at the beginning of each program:

.. testcode::

    from skyfield import api
    ts = api.load.timescale()

It downloads and parses the data tables necessary
to correctly convert between Universal Time
and the more stable time scales used by astronomers.

If you want to skip downloading up-to-date time scale files,
you can run:

.. testcode::

    ts = api.load.timescale(builtin=True)

This can avoid problems connecting
to the servers from which the official files are distributed.
Note that the time scale files distributed with
any given version of Skyfield will fall gradually out of date.

.. autosummary::

   Timescale.now
   Timescale.from_datetime
   Timescale.from_datetimes
   Timescale.utc
   Timescale.tai
   Timescale.tai_jd
   Timescale.tt
   Timescale.tt_jd
   Timescale.tdb
   Timescale.tdb_jd
   Timescale.ut1
   Timescale.ut1_jd
   Timescale.from_astropy

Time objects
============

The `Time` class is Skyfield's way of representing
either a single time, or a whole array of times.
The same time can be represented in several different time scales.

========= ==================================================
``t.tai`` International Atomic Time (TAI) as a Julian date.
``t.tt``  Terrestrial Time (TT) as a Julian date.
``t.J``   Terrestrial Time (TT) as decimal Julian years.
``t.tdb`` Barycentric Dynamical Time (TDB) as a Julian date.
``t.ut1`` Universal Time (UT1) as a Julian date.
========= ==================================================

A couple of offsets between time scales are also available.

============= ================================
``t.delta_t`` Difference TT − UT1 in seconds.
``t.dut1``    Difference UT1 − UTC in seconds.
============= ================================

Other time scales and conversions are available through its methods.

.. autosummary::

   Time.utc_jpl
   Time.utc_iso
   Time.utc_strftime
   Time.utc_datetime
   Time.utc_datetime_and_leap_second
   Time.astimezone
   Time.astimezone_and_leap_second
   Time.toordinal
   Time.tai_calendar
   Time.tt_calendar
   Time.M
   Time.MT
   Time.gmst
   Time.gast
   Time.nutation_matrix
   Time.precession_matrix

Vector Functions
================

.. currentmodule:: skyfield.vectorlib

The common API shared by planets, Earth locations, and Earth satellites.

.. autosummary::

   VectorFunction
   VectorFunction.at

Either adding two vector functions ``v1 + v2`` or subtracting them ``v1 - v2``
produces a new function of time that, when invoked with ``.at(t)``,
returns the sum or difference of the vectors returned by the two functions.

Planetary Ephemerides
=====================

.. currentmodule:: skyfield.jpllib

By downloading a `SpiceKernel` file,
Skyfield users can build vector functions
predicting the positions of the Moon, Sun, and planets.
See :doc:`planets`.

.. autosummary::

   SpiceKernel
   SpiceKernel.close
   SpiceKernel.comments
   SpiceKernel.names
   SpiceKernel.decode

Kernels also support lookup using the Python ``kernel['Mars']`` syntax,
in which case they return a function of time
that returns vectors from the Solar System barycenter to the named body.

Almanac
=======

.. currentmodule:: skyfield.almanac

Routines to search for events like sunrise, sunset, and Moon phase.

.. autosummary::

   phase_angle
   fraction_illuminated
   seasons
   sunrise_sunset
   dark_twilight_day
   moon_phases

Topocentric Locations
=====================

.. currentmodule:: skyfield.toposlib

You can create a vector function
that computes the location of any position on the Earth’s surface.

.. autosummary::

   Topos

Kepler Orbits
=============

See :doc:`kepler-orbits`
for computing the positions of comets, asteroids, and other minor planets.

Earth Satellites
================

.. currentmodule:: skyfield.sgp4lib

By downloading TLE satellite element sets,
Skyfield users can build vector functions
that predict their positions.
See :doc:`earth-satellites`.

.. autosummary::

   EarthSatellite
   EarthSatellite.from_satrec

Stars and other distant objects
===============================

.. currentmodule:: skyfield.starlib

.. autosummary::
   :nosignatures:

   Star

Planetary reference frames
==========================

.. currentmodule:: skyfield.planetarylib

.. autosummary::
   :nosignatures:

   PlanetaryConstants
   Frame

Astronomical positions
======================

.. currentmodule:: skyfield.positionlib

The `ICRF` three-dimensional position vector serves as the base class
for all of the following position classes.  Each class represents an
(x,y,z) ``.position`` and ``.velocity`` in the International Terrestrial
Reference Frame (ITRF), an inertial system that is an update to J2000
and that does not rotate with the Earth itself.

.. autosummary::
   :nosignatures:

   ICRF
   Barycentric
   Astrometric
   Apparent
   Geocentric

Positions are usually generated by the ``at(t)`` method of a vector
function, rather than being constructed manually.  But you can also
build a position directly from a raw vector, or from right ascension and
declination coordinates with
:func:`skyfield.positionlib.position_of_radec()`.

.. autosummary::

   position_of_radec

Position methods and attributes
===============================

All position objects have three attributes
which provide access to their raw data:

================= ==================================
``ICRF.t``        The `Time` of the position.
``ICRF.position`` A `Distance` array giving x, y, z.
``ICRF.velocity`` A `Velocity` array giving ẋ, ẏ, ż.
================= ==================================

If a position lacks a velocity,
then the attribute is simply the value ``None``.

All positions support a basic set of methods:

.. autosummary::

   ICRF.distance
   ICRF.speed
   ICRF.radec
   ICRF.separation_from
   ICRF.ecliptic_xyz
   ICRF.ecliptic_velocity
   ICRF.ecliptic_latlon
   ICRF.galactic_xyz
   ICRF.galactic_latlon
   ICRF.is_sunlit
   ICRF.from_altaz

Position methods specific to one class
======================================

.. autosummary::

   Barycentric.observe
   Astrometric.apparent
   Apparent.altaz
   Geocentric.subpoint

Constellations
==============

.. autofunction:: skyfield.api.load_constellation_map

Searching
=========

.. currentmodule:: skyfield.searchlib

.. autofunction:: find_discrete()
.. autofunction:: find_maxima()
.. autofunction:: find_minima()

Osculating Orbital Elements
===========================

This routine returns osculating orbital elements for an object’s
instantaneous position and velocity.

.. currentmodule:: skyfield.elementslib

.. autosummary::

   osculating_elements_of

================================================== ============================
``OsculatingElements.apoapsis_distance``           Distance object
``OsculatingElements.argument_of_latitude``        Angle object
``OsculatingElements.argument_of_periapsis``       Angle object
``OsculatingElements.eccentric_anomaly``           Angle object
``OsculatingElements.eccentricity``                numpy.ndarray
``OsculatingElements.inclination``                 Angle object
``OsculatingElements.longitude_of_ascending_node`` Angle object
``OsculatingElements.longitude_of_periapsis``      Angle object
``OsculatingElements.mean_anomaly``                Angle object
``OsculatingElements.mean_longitude``              Angle object
``OsculatingElements.mean_motion_per_day``         Angle object
``OsculatingElements.periapsis_distance``          Distance object
``OsculatingElements.periapsis_time``              Time object
``OsculatingElements.period_in_days``              numpy.ndarray
``OsculatingElements.semi_latus_rectum``           Distance object
``OsculatingElements.semi_major_axis``             Distance object
``OsculatingElements.semi_minor_axis``             Distance object
``OsculatingElements.time``                        Time object
``OsculatingElements.true_anomaly``                Angle object
``OsculatingElements.true_longitude``              Angle object
================================================== ============================

Units
=====

.. currentmodule:: skyfield.units

===================== ==================================================
`Distance`            Distance measure.
``Distance.au``       Astronomical Units.
``Distance.km``       Kilometers.
``Distance.m``        Meters.
`Velocity`            Velocity measure.
``Velocity.au_per_d`` Astronomical Units.
``Velocity.km_per_s`` Kilometers.
`Angle`               Angle measure.
``Angle.degrees``     Degrees of arc (360 in a complete circle).
``Angle.hours``       Hours of arc (24 in a complete circle).
``Angle.radians``     Radians (τ = 2π in a complete circle).
===================== ==================================================

All three kinds of quantity support one or more methods.

.. autosummary::

   Distance.length
   Distance.light_seconds
   Distance.to
   Velocity.to
   Angle.arcminutes
   Angle.arcseconds
   Angle.mas
   Angle.to
   Angle.hms
   Angle.signed_hms
   Angle.hstr
   Angle.dms
   Angle.signed_dms
   Angle.dstr

Trigonometry
============

.. currentmodule:: skyfield.trigonometry

.. autosummary::

   position_angle_of
