API Reference — Planetary Ephemerides¶

JPL .bsp ephemeris files¶

class skyfield.jpllib.SpiceKernel(path)¶

Ephemeris file in NASA .bsp format.

A “Spacecraft and Planet Kernel” (SPK) file from NASA provides (x,y,z) coordinates for bodies in the Solar System like the Sun, planets, moons, and spacecraft.

You can download a .bsp file yourself and use this class to open it, or use the Skyfield load() function to automatically download a popular ephemeris. Once loaded, you can print this object to the screen to see a report on the segments that it includes:

>>> planets = load('de421.bsp')
>>> print(planets)
SPICE kernel file 'de421.bsp' has 15 segments
  JD 2414864.50 - JD 2471184.50  (1899-07-28 through 2053-10-08)
      0 -> 1    SOLAR SYSTEM BARYCENTER -> MERCURY BARYCENTER
      0 -> 2    SOLAR SYSTEM BARYCENTER -> VENUS BARYCENTER
      0 -> 3    SOLAR SYSTEM BARYCENTER -> EARTH BARYCENTER
      0 -> 4    SOLAR SYSTEM BARYCENTER -> MARS BARYCENTER
      0 -> 5    SOLAR SYSTEM BARYCENTER -> JUPITER BARYCENTER
      0 -> 6    SOLAR SYSTEM BARYCENTER -> SATURN BARYCENTER
      0 -> 7    SOLAR SYSTEM BARYCENTER -> URANUS BARYCENTER
      0 -> 8    SOLAR SYSTEM BARYCENTER -> NEPTUNE BARYCENTER
      0 -> 9    SOLAR SYSTEM BARYCENTER -> PLUTO BARYCENTER
      0 -> 10   SOLAR SYSTEM BARYCENTER -> SUN
      3 -> 301  EARTH BARYCENTER -> MOON
      3 -> 399  EARTH BARYCENTER -> EARTH
      1 -> 199  MERCURY BARYCENTER -> MERCURY
      2 -> 299  VENUS BARYCENTER -> VENUS
      4 -> 499  MARS BARYCENTER -> MARS

To retrieve the one or more vectors necessary to compute the position of a body relative to the Solar System barycenter, look up the body by its name or official SPICE identifying integer:

>>> planets['earth']
<VectorSum of 2 vectors:
 'de421.bsp' segment 0 SOLAR SYSTEM BARYCENTER -> 3 EARTH BARYCENTER
 'de421.bsp' segment 3 EARTH BARYCENTER -> 399 EARTH>
>>> planets[499]
<VectorSum of 2 vectors:
 'de421.bsp' segment 0 SOLAR SYSTEM BARYCENTER -> 4 MARS BARYCENTER
 'de421.bsp' segment 4 MARS BARYCENTER -> 499 MARS>

The result will be a VectorFunction instance that you can ask for a position at a given input time.

close()¶

Close this ephemeris file.

comments()¶

Return the comments string of this kernel.

The resulting string often contains embedded newlines, and is formatted for a human reader.

>>> print(planets.comments())
; de421.bsp LOG FILE
;
; Created 2008-02-12/11:33:34.00.
...
LEAPSECONDS_FILE    = naif0007.tls
SPK_FILE            = de421.bsp
...

names()¶

Return all target names that are valid with this kernel.

>>> pprint(planets.names())
{0: ['SOLAR_SYSTEM_BARYCENTER', 'SSB', 'SOLAR SYSTEM BARYCENTER'],
 1: ['MERCURY_BARYCENTER', 'MERCURY BARYCENTER'],
 2: ['VENUS_BARYCENTER', 'VENUS BARYCENTER'],
 3: ['EARTH_BARYCENTER',
     'EMB',
 ...

The result is a dictionary with target code keys and name lists as values. The last name in each list is the one that Skyfield uses when printing information about a body.

decode(name)¶

Translate a target name into its integer code.

>>> planets.decode('Venus')
299

Raises ValueError if you supply an unknown name, or KeyError if the target is missing from this kernel. You can supply an integer code if you already have one and just want to check whether it is present in this kernel.