=============== 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