DOCSEARCHbyAlgolia
Submit Docs

Skyfield Documentation

repository·master·Indexed 23 days ago

https://github.com/skyfielders/python-skyfield

A pure-Python astronomy package for generating high-precision, research-grade positions for planets and Earth satellites. Compatible with Python 2 and 3, it includes tools for almanac computations such as finding risings, settings, moon phases, equinoxes, solstices, and planetary oppositions and conjunctions.

Tokens
37.7K
Snippets
117
Records
213
Agent score
80%

What's inside Skyfield

  1. Use standard reference frames from skyfield.framelib

    master

    The skyfield.framelib module provides access to standard astronomical and terrestrial reference frames. You can use these frames to define coordinate systems for positions and orientations.

    Available frames include:

    • Terrestrial Frames: itrs (International Terrestrial Reference System).
    • Ecliptic Frames: ecliptic_frame and ecliptic_J2000_frame.
    • Galactic Frames: galactic_frame.
    • Equatorial Frames: mean_equator_and_equinox_of_date and true_equator_and_equinox_of_date.

    These frames are typically used in conjunction with Skyfield's position and velocity calculations to transform coordinates between different celestial or terrestrial perspectives.

  2. Use skyfield.almanac for astronomical event searches

    master
    The skyfield.almanac module provides routines to search for specific astronomical events over a time range. This includes finding times for risings, settings, transits, and discrete events like moon phases or seasons. For detailed guidance on how to use these routines to find sunrise, sunset, or moon phases, refer to the almanac documentation guide.

  4. Understand Skyfield's distance handling for stars

    master
    When a Star is initialized with only RA and Dec (and no parallax), Skyfield cannot determine its distance. In these cases, it returns a distance of exactly 1 gigaparsec (approx $2.06265 imes 10^{14}$ au) to represent an unknown vector length. Real stellar distances are typically within a few hundred parsecs; a distance of 1 gigaparsec is a clear indicator that parallax data was not provided.

  5. Understand the ICRS reference system

    master

    Skyfield stores all positions internally as Cartesian $|xyz|$ vectors oriented along the axes of the International Celestial Reference System (ICRS). This is a high-accuracy system based on distant quasars and is the modern replacement for the J2000 system.

    The ICRS axes are defined as:

    • x-axis: Aims at the 2000 January 1 position of the Vernal Equinox.
    • y-axis: Aims at the point 90° east of the Vernal Equinox along the celestial equator.
    • z-axis: Aims at the North Celestial Pole.

  6. Distinguish between Positions and Coordinates in Skyfield

    master

    Skyfield uses a strict distinction between Positions (physical locations in the sky) and Coordinates (the numerical names used to describe those locations). This distinction helps prevent errors when switching between different astronomical models or reference frames.

    Positions

    Positions are treated as substantial Python objects. If you perform an operation that changes the physical location being described (e.g., converting an astrometric position to an apparent position), Skyfield returns a new object.

    Coordinates

    Coordinates are treated as mere names for a position. Changing the coordinate system (e.g., from equatorial to ecliptic) does not change the physical location, so it does not return a new object. Instead, you call different methods on the existing position object to get the desired coordinate values.

    Key API Pattern:

    • Use methods like .apparent() to get a new position object.
    • Use methods like .radec(), .ecliptic_latlon(), or .galactic_latlon() to get coordinate values from a position object.
    # Converting to a different physical position returns a new object
apparent = astrometric.apparent()

# Getting different coordinate names for the same position uses methods
astrometric.radec()
astrometric.ecliptic_latlon()
astrometric.galactic_latlon()

  7. Use the Loader class to manage data files

    master
    The Loader class in skyfield.iokit is the central mechanism for downloading and opening the data files required for Skyfield operations. It manages a local cache of files. When you attempt to open a file, the Loader first checks its designated directory. If the file is not found locally, it downloads the file to that directory.

  8. Use Time objects and time scales

    master

    The Time class represents a single time or an array of times. You can access various time scales as attributes of a Time object (represented as Julian dates) or via methods.

    Common Julian Date attributes:

    • t.tai: International Atomic Time (TAI)
    • t.tt: Terrestrial Time (TT)
    • t.J: Terrestrial Time (TT) as floating point Julian years
    • t.tdb: Barycentric Dynamical Time (TDB)
    • t.ut1: Universal Time (UT1)

    Common offsets:

    • t.delta_t: Difference TT − UT1 in seconds.
    • t.dut1: Difference UT1 − UTC in seconds.

  9. Manage time scales with the Timescale object

    master

    The Timescale object, typically created via load.timescale(), manages conversions between different time scales and is used to construct Time objects. It is a best practice to create a single Timescale object (conventionally named ts) and use it for all time constructions in an application.

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

  10. Use specialized position classes (Barycentric, Astrometric, Apparent, Geocentric)

    master

    Skyfield provides specialized subclasses of ICRF to represent different astronomical perspectives. These classes inherit all methods from ICRF and maintain the same axis orientation in space:

    • Barycentric: Position measured from the Solar System barycenter.
    • Astrometric: Position relative to an observer (topocentric/geocentric/etc. without light-travel time corrections).
    • Apparent: Position relative to an observer, accounting for effects like light-travel time and aberration.
    • Geocentric: Position relative to the Earth.

  11. Work with Vector functions

    master

    Vector functions (shared by planets, Earth locations, and satellites) represent positions or velocities that change over time. You can evaluate them at a specific time using the .at(t) method.

    You can also perform vector arithmetic on these functions. Adding or subtracting two vector functions (v1 + v2 or v1 - v2) produces a new function of time. When invoked with .at(t), this new function returns the sum or difference of the vectors returned by the original two functions.

  12. How to handle phase_angle() requirements

    master
    The phase_angle() method requires the position to already know its barycentric center because it only computes the position of the Sun. Unlike is_sunlit(), which can work with a bare Earth satellite by computing both Earth and Sun positions, phase_angle() requires the user to provide or ensure the position is barycentric.