planetEphemeris

Position and velocity of astronomical objects

Syntax

position = planetEphemeris(ephemerisTime,center,target)

position = planetEphemeris(___,ephemerisModel)

position = planetEphemeris(___,units)

position = planetEphemeris(___,action)

position = planetEphemeris(___,Name=Value)

[position,velocity] = planetEphemeris(___)

Description

Implement Planet Ephemeris Position

position = planetEphemeris(ephemerisTime,center,target) implements the position of the target object relative to the specified center object for a given Julian date ephemerisTime. By default, the function implements the position based on the DE405 ephemerides in units of km.

The function uses the Chebyshev coefficients that the NASA Jet Propulsion Laboratory provides.

This function requires that you download ephemeris data with the Add-On Explorer. For more information, see aeroDataPackage.

position = planetEphemeris(___,ephemerisModel) uses the ephemerisModel coefficients to implement these values.

position = planetEphemeris(___,units) specifies the units for these values.

position = planetEphemeris(___,action) uses action to determine error reporting.

position = planetEphemeris(___,Name=Value) uses Name=Value to limit the data that is loaded into memory to the range between StartDate and EndDate.

Implement Planet Ephemeris Position and Velocity

[position,velocity] = planetEphemeris(___) implements the position and velocity of the target object relative to the specified center for a given Julian date ephemerisTime using any of the input arguments in the previous syntaxes.

Examples

Implement Position of Moon

Implement the position of the Moon with respect to the Earth for December 1, 1990, with DE405.

position = planetEphemeris(juliandate(1990,12,1),'Earth','Moon')

position = 1×3
105 ×

    2.3112    2.3817    1.3595

Implement Position and Velocity for Saturn

Implement the position and velocity for Saturn with respect to the Solar System barycenter for noon on January 1, 2000, using DE421 and AU units.

[position,velocity] = planetEphemeris([2451544.5 0.5],...
'SolarSystem','Saturn','421','AU')

position = 1×3

    6.3993    6.1720    2.2738

velocity = 1×3

   -0.0043    0.0035    0.0016

Implement Position and Velocity of Mars with Respect to Earth

Implement the position and velocity of Mars with respect to Earth using start and end dates. Load data only for dates between 2020-2022.

For a start date of noon on January 1, 2020.

[position1,velocity1] = planetEphemeris(juliandate(2020,1,1,12,0,0),'Earth','Mars',...
    StartDate=juliandate(2020,1,1), EndDate=juliandate(2022,1,1))

position1 = 1×3
108 ×

   -1.7069   -2.5591   -1.0872

velocity1 = 1×3

   44.2929  -11.2378   -5.6713

For a start date of noon on January 1, 2021.

[position2,velocity2] = planetEphemeris(juliandate(2021,1,1,12,0,0),'Earth','Mars', ...
    StartDate=juliandate(2020,1,1), EndDate=juliandate(2022,1,1))

position2 = 1×3
108 ×

    1.2005    0.5599    0.2654

velocity2 = 1×3

    8.5044   15.9473    7.7539

Input Arguments

ephemerisTime — Julian date

scalar | 2-element vector | column vector | M-by-2 matrix

Julian date for which positions are calculated, specified as one of these values:

• Scalar — Specify one fixed Julian date.

• 2-element vector — Specify the Julian date in multiple parts. The first element is the Julian date for a specific epoch that is the most recent midnight at or before the interpolation epoch. The second element is the fractional part of a day elapsed between the first element and epoch. The second element must be positive. The value of the first element plus the second element cannot exceed the maximum Julian date.

• Column vector — Specify a column vector with M elements, where M is the number of fixed Julian dates.

• M-by-2 matrix — Specify a matrix, where M is the number of Julian dates (Julian epoch date) and the second column contains the elapsed days (elapsed day pairs).

Specify the Julian dates in Barycentric Dynamical Time (TDB).

Data Types: double

center — Reference body (astronomical object) or point of reference

'Sun' | 'Mercury' | 'Venus' | 'Earth' | 'Moon' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Pluto' | 'SolarSystem' | 'EarthMoon'

Reference body (astronomical object) or point of reference from which to measure the target position and velocity, specified as 'Sun', 'Mercury', 'Venus', 'Earth', 'Moon', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', 'Pluto''SolarSystem', or 'EarthMoon'.

Data Types: char

target — Target body (astronomical object) or point of reference

'Sun' | 'Mercury' | 'Venus' | 'Earth' | 'Moon' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Pluto' | 'SolarSystem' | 'EarthMoon'

Target body (astronomical object) or point of reference of the position and velocity measurement, specified as 'Sun', 'Mercury', 'Venus', 'Earth', 'Moon', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', 'Pluto''SolarSystem', or 'EarthMoon'.

Data Types: char

ephemerisModel — Ephemerides coefficients

'405' (default) | '421' | '423' | '430' | '432t'

Ephemerides coefficients, specified as one of these ephemerides defined by the Jet Propulsion Laboratory:

• '405' — Released in 1998. This ephemerides takes into account the Julian date range 2305424.50 (December 9, 1599 ) to 2525008.50 (February 20, 2201).

  This function calculates these ephemerides with respect to the International Celestial Reference Frame version 1.0, adopted in 1998.

• '421' — Released in 2008. This ephemerides takes into account the Julian date range 2414992.5 (December 4, 1899) to 2469808.5 (January 2, 2050).

  This function calculates these ephemerides with respect to the International Celestial Reference Frame version 1.0, adopted in 1998.

• '423' — Released in 2010. This ephemerides takes into account the Julian date range 2378480.5 (December 16, 1799) to 2524624.5 (February 1, 2200).

  This function calculates these ephemerides with respect to the International Celestial Reference Frame version 2.0, adopted in 2010.

• '430' — Released in 2013. This ephemerides takes into account the Julian date range 2287184.5 (December 21, 1549) to 2688976.5 (January 25, 2650).

  This function implements these ephemerides with respect to the International Celestial Reference Frame version 2.0, adopted in 2010.

• '432t'

  Released in April 2014. This ephemerides takes into account the Julian date range 2287184.5, (December 21, 1549 ) to 2688976.5, (January 25, 2650).

  This function implements these ephemerides with respect to the International Celestial Reference Frame version 2.0, adopted in 2010.

Data Types: char

units — Output units

'km' (default) | 'AU'

Output units for position and velocity, specified as 'km' for km and km/s or 'AU' for astronomical units or AU/day.

Data Types: char

action — Function behavior

'Error' (default) | 'None' | 'Warning'

Function behavior when inputs are out of range, specified as one of these values.

Value	Description
'None'	No action.
'Warning'	Warning in the MATLAB® Command Window and model simulation continues.
'Error'	MATLAB returns an exception and model simulation stops.

Data Types: char

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: StartDate=juliandate(2020,1,1) specifies the start date is the result of juliandate(2020,1,1),2.4588e+06.

StartDate — Start date of ephemerides date range

start date of current ephemeris model (default) | Julian date

Start date of ephemerides date range, specified as a Julian date. This argument limits the amount of data that is loaded and kept in persistent memory between calls to the function.

Data Types: char | string

EndDate — End date of ephemerides date range

end date of current ephemeris model (default) | Julian date

End date of ephemerides date range, specified as a Julian date. This argument limits the amount of data that is loaded and kept in persistent memory between calls to the function.

Data Types: char | string

Output Arguments

position — Position of target

M-by-3 vector

Position of the target object relative to the center object, returned as an M-by-3 vector, where M is the number of Julian dates. The 3 columns contain the x, y, and z of the position along the International Celestial Reference Frame (ICRF). Units are km or astronomical units (AU). If input arguments include multiple Julian dates or epochs, this vector has the same number of rows as the ephemerisTime input.

velocity — Velocity of target

M-by-3 vector

Velocity of the target object relative to the center object, returned as an M-by-3 vector, where M is the number of Julian dates. The 3 vector contains the velocity in the x, y, and z directions along the ICRF. Velocity of the Units are km or astronomical units (AU). If the input includes multiple Julian dates or epochs, this vector has the same number of rows as the ephemerisTime input.

References

[1] Folkner, W. M., J. G. Williams, and D. H. Boggs. "The Planetary and Lunar Ephemeris DE 421." JPL Interplanetary Network Progress Report 24-178, 2009.

[2] Ma, C. et al., “The International Celestial Reference Frame as Realized by Very Long Baseline Interferometry,” Astronomical Journal, Vol. 116 (1998): 516–546.

[3] Vallado, David A., Fundamentals of Astrodynamics and Applications. New York: McGraw-Hill, 1997.

Version History

Introduced in R2013a

R2023b: planetEphemeris Function Date Range

The planetEphemeris now controls the date range of the ephemeris data loaded.