JPLephem is a PHP package capable of reading Jet Propulsion Laboratory Development Ephemeris (JPL DE) files and caclulating the positions and velocities of the major planets, the Sun and Earth's Moon. The package can also interpolate additional information held within the ephemeris files (depending upon the DE version) such as the Earth's Nutations in longitude and obliquity according to the IAU 1980 model, lunar mantle librations and angular velocity as well as the value of TT-TDB at the geocenter.
$ composer require marando/jplephem
Usage is fairly straightfoward, first you'll want to import the reader class and instantiate a new reader instance:
use \Marando\JPLephem\DE\Reader;
$de = new Reader();
Then just specify the observation JDE:
// JDE should be in Barycentric Dynamical Time (TDB)
$de->jde(2451545.5);
And you're ready to interpolate positions!
Solar system barycentric positions can be found by calling the position()
method with only the first parameter as shown:
$de->position(SSObj::Mercury());
$de->position(SSObj::Pluto());
The position()
method returns an array of six values representing respectively the position x, y and z and velocity x, y and z coordinates. For example:
print_r( $de->position(SSObj::Pluto()) );
Output:
Array
(
[0] => -9.8809726622956 // x position
[1] => -27.982087174796 // y position
[2] => -5.7552504336267 // z position
[3] => 0.0030341820284709 // x velocity
[4] => -0.0011342010879702 // y velocity
[5] => -0.0012681328951126 // z velocity
)
By default the distance units are in AU and the velocity units are in AU/day, but they can be changed to km and km/day by using the following methods:
$de->km(); // Use km & km/day
$de->au(); // Use AU & AU/day
To find the relative position of a target body with respect to a defined center body, simply call the position()
method as above, and provided a second argument defining the center:
// Target // Center
$de->position(SSObj::Pluto(), SSObj::Mercury());
You can also find positions adjusted for light travel time by calling the observe()
method:
$de->observe(SSObj::Pluto(), SSObj::Earth());
To get the light-time simply supply a third pass-by reference variable to the call:
$de->observe(SSObj::Pluto(), SSObj::Earth(), $lt);
echo $lt; // Result: 0.179 days
Depending on the DE version, there may be additional information held within the ephemeris files, such as the Earth's nutations and lunar libration angles. To interpolate these values you can use the interp()
method and provide the element number and number of components shown below (which can be found in JPL's documentation)
Description | Element | Components | Units |
---|---|---|---|
Mercury—Pluto, Sun & Moon | 1–11 | 6 | au, au/day |
Earth Nutations (IAU 1980 model) | 12 | 2 | radians |
Lunar mantle libration | 13 | 3 | radians |
Lunar mantle angular velocity | 14 | 3 | radians/day |
TT-TDB (at geocenter) | 15 or 17 | 1 | seconds |
For example, to find the Earth's nutations in longitude and obliquity according to the 1980 IAU model, you first need to know that the nutations are element 12 and there are 2 components, then call:
$nutations = $de->interp(12, 2);
The results are an array in the units specified by the DE version. For example, for the Earth's nutations, the first element is nutation in longitude (Δψ), and the second is nutation in obliquity (Δε), and in this case both values are expressed radians:
Array
(
[0] => -6.7464277868885E-5 // Δψ in radians
[1] => -2.8042821016313E-5 // Δε in radians
)
Because of its small size, DE421
is the default version, and exists as a composer dependency that will be automatically downloaded when this package is installed. If you wish to use a different DE version you'll have to require that version in your project's composer.json
file, or use the composer require
command to install it.
For example:
composer require marando/de430
The above command will install DE430 to your project, which you can then use like so:
$DE430 = new Reader(DE::DE430());
Note: Currently only DE421 and DE430 are available, but more are likely to come in the future.