2014-01-16 04:57:59 +01:00
|
|
|
|
|
2018-05-19 23:10:54 +02:00
|
|
|
|
===============
|
|
|
|
|
API Reference
|
|
|
|
|
===============
|
2014-08-19 00:09:14 +02:00
|
|
|
|
|
2019-10-09 21:36:36 +02:00
|
|
|
|
Quick links to the sections below:
|
|
|
|
|
|
|
|
|
|
.. contents:: :local:
|
|
|
|
|
|
2018-02-11 21:30:33 +01:00
|
|
|
|
Opening files
|
|
|
|
|
=============
|
2016-03-30 16:34:08 +02:00
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.iokit
|
|
|
|
|
|
2016-07-10 23:22:06 +02:00
|
|
|
|
::
|
|
|
|
|
|
2018-02-11 21:30:33 +01:00
|
|
|
|
# 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.
|
|
|
|
|
|
2016-07-10 23:22:06 +02:00
|
|
|
|
from skyfield.api import load
|
|
|
|
|
ts = load.timescale()
|
|
|
|
|
planets = load('de405.bsp')
|
|
|
|
|
|
2016-03-30 16:34:08 +02:00
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
Loader
|
2020-05-31 18:17:43 +02:00
|
|
|
|
Loader.build_url
|
2016-07-10 23:22:06 +02:00
|
|
|
|
Loader.path_to
|
|
|
|
|
Loader.timescale
|
2020-03-24 14:17:46 +01:00
|
|
|
|
Loader.tle_file
|
2016-03-27 05:23:59 +02:00
|
|
|
|
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Time scales
|
|
|
|
|
===========
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.timelib
|
|
|
|
|
|
|
|
|
|
A Skyfield `Timescale` object is typically built
|
2019-03-30 14:26:54 +01:00
|
|
|
|
at the beginning of each program:
|
|
|
|
|
|
|
|
|
|
.. testcode::
|
2017-03-15 05:05:12 +01:00
|
|
|
|
|
|
|
|
|
from skyfield import api
|
2019-03-30 14:26:54 +01:00
|
|
|
|
ts = api.load.timescale()
|
2017-03-15 05:05:12 +01:00
|
|
|
|
|
|
|
|
|
It downloads and parses the data tables necessary
|
|
|
|
|
to correctly convert between Universal Time
|
|
|
|
|
and the more stable time scales used by astronomers.
|
|
|
|
|
|
2019-07-21 01:48:22 +02:00
|
|
|
|
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.
|
|
|
|
|
|
2017-03-15 05:05:12 +01:00
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
Timescale.now
|
2020-07-17 15:41:48 +02:00
|
|
|
|
Timescale.from_datetime
|
|
|
|
|
Timescale.from_datetimes
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Timescale.utc
|
|
|
|
|
Timescale.tai
|
2018-07-09 03:31:50 +02:00
|
|
|
|
Timescale.tai_jd
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Timescale.tt
|
2018-07-09 03:31:50 +02:00
|
|
|
|
Timescale.tt_jd
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Timescale.tdb
|
2018-07-09 03:31:50 +02:00
|
|
|
|
Timescale.tdb_jd
|
2018-05-21 02:49:09 +02:00
|
|
|
|
Timescale.ut1
|
2018-07-09 03:31:50 +02:00
|
|
|
|
Timescale.ut1_jd
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Timescale.from_astropy
|
|
|
|
|
|
|
|
|
|
Time objects
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
The `Time` class is Skyfield's way of representing
|
|
|
|
|
either a single time, or a whole array of times.
|
2020-06-07 17:12:11 +02:00
|
|
|
|
The same time can be represented in several different time scales.
|
2017-03-15 05:05:12 +01:00
|
|
|
|
|
|
|
|
|
========= ==================================================
|
|
|
|
|
``t.tai`` International Atomic Time (TAI) as a Julian date.
|
|
|
|
|
``t.tt`` Terrestrial Time (TT) as a Julian date.
|
2018-05-21 03:04:36 +02:00
|
|
|
|
``t.J`` Terrestrial Time (TT) as decimal Julian years.
|
2017-03-15 05:05:12 +01:00
|
|
|
|
``t.tdb`` Barycentric Dynamical Time (TDB) as a Julian date.
|
|
|
|
|
``t.ut1`` Universal Time (UT1) as a Julian date.
|
|
|
|
|
========= ==================================================
|
|
|
|
|
|
2018-05-21 02:49:09 +02:00
|
|
|
|
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.
|
|
|
|
|
============= ================================
|
|
|
|
|
|
2017-03-15 05:05:12 +01:00
|
|
|
|
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
|
2020-06-07 17:12:11 +02:00
|
|
|
|
Time.M
|
|
|
|
|
Time.MT
|
|
|
|
|
Time.gmst
|
|
|
|
|
Time.gast
|
|
|
|
|
Time.nutation_matrix
|
|
|
|
|
Time.precession_matrix
|
2017-03-15 05:05:12 +01:00
|
|
|
|
|
2017-03-15 02:54:00 +01:00
|
|
|
|
Vector Functions
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.vectorlib
|
|
|
|
|
|
|
|
|
|
The common API shared by planets, Earth locations, and Earth satellites.
|
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
VectorFunction
|
|
|
|
|
VectorFunction.at
|
|
|
|
|
|
2020-06-15 19:45:35 +02:00
|
|
|
|
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.
|
|
|
|
|
|
2017-03-15 02:54:00 +01:00
|
|
|
|
Planetary Ephemerides
|
|
|
|
|
=====================
|
2016-03-27 05:23:59 +02:00
|
|
|
|
|
2016-03-30 16:34:08 +02:00
|
|
|
|
.. currentmodule:: skyfield.jpllib
|
|
|
|
|
|
2017-03-15 02:54:00 +01:00
|
|
|
|
By downloading a `SpiceKernel` file,
|
|
|
|
|
Skyfield users can build vector functions
|
|
|
|
|
predicting the positions of the Moon, Sun, and planets.
|
2020-06-04 18:09:01 +02:00
|
|
|
|
See :doc:`planets`.
|
2016-03-27 05:23:59 +02:00
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
SpiceKernel
|
2020-06-04 18:09:01 +02:00
|
|
|
|
SpiceKernel.close
|
2016-03-28 15:57:29 +02:00
|
|
|
|
SpiceKernel.comments
|
2016-03-28 11:22:05 +02:00
|
|
|
|
SpiceKernel.names
|
2016-03-27 05:23:59 +02:00
|
|
|
|
SpiceKernel.decode
|
2020-06-15 19:45:35 +02:00
|
|
|
|
|
|
|
|
|
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.
|
2017-03-15 02:54:00 +01:00
|
|
|
|
|
2018-09-12 13:06:49 +02:00
|
|
|
|
Almanac
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.almanac
|
|
|
|
|
|
|
|
|
|
Routines to search for events like sunrise, sunset, and Moon phase.
|
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
phase_angle
|
|
|
|
|
fraction_illuminated
|
2018-09-23 23:00:00 +02:00
|
|
|
|
seasons
|
2018-09-12 13:06:49 +02:00
|
|
|
|
sunrise_sunset
|
2019-11-08 18:49:33 +01:00
|
|
|
|
dark_twilight_day
|
2018-09-12 13:06:49 +02:00
|
|
|
|
moon_phases
|
|
|
|
|
|
2017-03-15 02:54:00 +01:00
|
|
|
|
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
|
|
|
|
|
|
2020-07-07 21:17:52 +02:00
|
|
|
|
Kepler Orbits
|
|
|
|
|
=============
|
|
|
|
|
|
|
|
|
|
See :doc:`kepler-orbits`
|
|
|
|
|
for computing the positions of comets, asteroids, and other minor planets.
|
|
|
|
|
|
2017-03-15 02:54:00 +01:00
|
|
|
|
Earth Satellites
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.sgp4lib
|
|
|
|
|
|
|
|
|
|
By downloading TLE satellite element sets,
|
|
|
|
|
Skyfield users can build vector functions
|
|
|
|
|
that predict their positions.
|
2020-03-24 14:17:46 +01:00
|
|
|
|
See :doc:`earth-satellites`.
|
2017-03-15 02:54:00 +01:00
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
EarthSatellite
|
2020-06-08 16:46:59 +02:00
|
|
|
|
EarthSatellite.from_satrec
|
2016-03-27 05:23:59 +02:00
|
|
|
|
|
2016-07-10 04:07:31 +02:00
|
|
|
|
Stars and other distant objects
|
|
|
|
|
===============================
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.starlib
|
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
:nosignatures:
|
|
|
|
|
|
|
|
|
|
Star
|
|
|
|
|
|
2019-12-20 17:33:02 +01:00
|
|
|
|
Planetary reference frames
|
|
|
|
|
==========================
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.planetarylib
|
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
:nosignatures:
|
|
|
|
|
|
|
|
|
|
PlanetaryConstants
|
|
|
|
|
Frame
|
|
|
|
|
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Astronomical positions
|
|
|
|
|
======================
|
2016-03-27 04:18:40 +02:00
|
|
|
|
|
2016-03-28 18:34:30 +02:00
|
|
|
|
.. currentmodule:: skyfield.positionlib
|
|
|
|
|
|
2019-10-09 13:05:49 +02:00
|
|
|
|
The `ICRF` three-dimensional position vector serves as the base class
|
2019-11-11 03:59:29 +01:00
|
|
|
|
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.
|
2016-03-27 04:18:40 +02:00
|
|
|
|
|
2016-03-26 23:43:43 +01:00
|
|
|
|
.. autosummary::
|
|
|
|
|
:nosignatures:
|
|
|
|
|
|
|
|
|
|
ICRF
|
|
|
|
|
Barycentric
|
|
|
|
|
Astrometric
|
|
|
|
|
Apparent
|
2016-03-27 04:18:40 +02:00
|
|
|
|
Geocentric
|
|
|
|
|
|
2019-10-09 13:05:49 +02:00
|
|
|
|
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
|
2020-05-20 16:24:34 +02:00
|
|
|
|
:func:`skyfield.positionlib.position_of_radec()`.
|
2019-10-09 13:05:49 +02:00
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
|
2020-05-20 16:24:34 +02:00
|
|
|
|
position_of_radec
|
2019-10-09 13:05:49 +02:00
|
|
|
|
|
2016-03-28 15:57:29 +02:00
|
|
|
|
Position methods and attributes
|
|
|
|
|
===============================
|
2016-03-26 23:43:43 +01:00
|
|
|
|
|
2016-03-28 18:34:30 +02:00
|
|
|
|
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:
|
|
|
|
|
|
2016-03-26 23:43:43 +01:00
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
ICRF.distance
|
2016-03-27 04:18:40 +02:00
|
|
|
|
ICRF.speed
|
2016-03-26 23:43:43 +01:00
|
|
|
|
ICRF.radec
|
2016-03-30 08:11:15 +02:00
|
|
|
|
ICRF.separation_from
|
2018-09-04 04:45:55 +02:00
|
|
|
|
ICRF.ecliptic_xyz
|
2018-07-27 04:57:35 +02:00
|
|
|
|
ICRF.ecliptic_velocity
|
2016-03-26 23:43:43 +01:00
|
|
|
|
ICRF.ecliptic_latlon
|
2018-09-04 04:45:55 +02:00
|
|
|
|
ICRF.galactic_xyz
|
2016-03-26 23:43:43 +01:00
|
|
|
|
ICRF.galactic_latlon
|
2020-05-28 20:50:48 +02:00
|
|
|
|
ICRF.is_sunlit
|
2016-03-27 04:18:40 +02:00
|
|
|
|
ICRF.from_altaz
|
|
|
|
|
|
2016-03-27 15:44:37 +02:00
|
|
|
|
Position methods specific to one class
|
|
|
|
|
======================================
|
2016-03-27 05:23:59 +02:00
|
|
|
|
|
2016-03-27 04:18:40 +02:00
|
|
|
|
.. autosummary::
|
|
|
|
|
|
2016-03-27 05:23:59 +02:00
|
|
|
|
Barycentric.observe
|
|
|
|
|
Astrometric.apparent
|
|
|
|
|
Apparent.altaz
|
2018-05-19 22:28:11 +02:00
|
|
|
|
Geocentric.subpoint
|
2016-03-26 23:43:43 +01:00
|
|
|
|
|
2019-10-09 21:36:36 +02:00
|
|
|
|
Constellations
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
.. autofunction:: skyfield.api.load_constellation_map
|
|
|
|
|
|
2020-06-15 19:45:35 +02:00
|
|
|
|
Searching
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.searchlib
|
|
|
|
|
|
|
|
|
|
.. autofunction:: find_discrete()
|
|
|
|
|
.. autofunction:: find_maxima()
|
|
|
|
|
.. autofunction:: find_minima()
|
|
|
|
|
|
2018-07-27 04:57:35 +02:00
|
|
|
|
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
|
|
|
|
|
================================================== ============================
|
|
|
|
|
|
2017-03-15 05:05:12 +01:00
|
|
|
|
Units
|
|
|
|
|
=====
|
2016-03-28 18:34:30 +02:00
|
|
|
|
|
2017-03-15 05:05:12 +01:00
|
|
|
|
.. currentmodule:: skyfield.units
|
2016-03-28 18:34:30 +02:00
|
|
|
|
|
|
|
|
|
===================== ==================================================
|
|
|
|
|
`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::
|
|
|
|
|
|
2020-05-30 04:28:00 +02:00
|
|
|
|
Distance.length
|
|
|
|
|
Distance.light_seconds
|
2016-03-28 18:34:30 +02:00
|
|
|
|
Distance.to
|
|
|
|
|
Velocity.to
|
2020-05-27 19:26:20 +02:00
|
|
|
|
Angle.arcminutes
|
|
|
|
|
Angle.arcseconds
|
|
|
|
|
Angle.mas
|
2016-03-28 18:34:30 +02:00
|
|
|
|
Angle.to
|
|
|
|
|
Angle.hms
|
|
|
|
|
Angle.signed_hms
|
|
|
|
|
Angle.hstr
|
|
|
|
|
Angle.dms
|
|
|
|
|
Angle.signed_dms
|
|
|
|
|
Angle.dstr
|
2019-12-06 00:25:27 +01:00
|
|
|
|
|
|
|
|
|
Trigonometry
|
|
|
|
|
============
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: skyfield.trigonometry
|
|
|
|
|
|
|
|
|
|
.. autosummary::
|
|
|
|
|
|
|
|
|
|
position_angle_of
|