External Data

DME Component Libraries makes use of various data in order to perform accurate calculations. This topic provides an overview of the data sources, the default data shipped with the libraries, and where to obtain updated data files.

Leap Seconds

Leap seconds are periodically introduced by the International Earth Rotation Service (IERS). In DME Component Libraries, the set of leap seconds used for calculations are managed by the LeapSecondsFacet. Each release of DME Component Libraries includes the full set of leap seconds, both past and future, known at the time of the release. However, because leap seconds are added unpredictably over time, if you are building an application that you expect to be deployed long-term, you may need to plan to update the set of leap seconds used in your application, by loading an external data file which you can update without needing to rebuild.

Leap seconds can be loaded from a data file, LeapSecond.dat, which is maintained by AGI at: https://ftp.agi.com/pub/STKData/Astro/LeapSecond.dat. This file can be loaded using the following code:

Copy

LeapSecondsFacet leapSeconds = LeapSecondFile.ReadLeapSeconds(filename);
leapSeconds.UseInCurrentContext();

Alternatively, if your application has internet access, you can download the latest file from AGI using the following code:

Copy

LeapSecondsFacet leapSeconds = LeapSecondFile.DownloadLeapSeconds();
leapSeconds.UseInCurrentContext();

Earth Orientation Parameters (EOP)

EarthOrientationParameters specify Earth polar motion coordinates and the difference between UT1 and UTC, which change over time. DME Component Libraries does not ship with this data, and by default, no EOP data is used.

This data file is maintained by AGI at: https://ftp.agi.com/pub/DynamicEarthData/EOP-v1.1.txt. This file contains observed data from the last several years, as well as several months of predicted values. A much larger file containing decades of historical data is available at: https://ftp.agi.com/pub/DynamicEarthData/EOP-All-v1.1.txt.

To load this data for use in DME Component Libraries, use EarthOrientationParametersFile to create an instance of EarthOrientationParameters, then store that object on EarthCentralBodyOrientationParameters.

Copy

EarthOrientationParameters eop = EarthOrientationParametersFile.ReadData(Path.Combine(dataPath, "EOP-v1.1.txt"));
CentralBodiesFacet.GetFromContext().Earth.OrientationParameters = eop;

Alternatively, if your application has internet access, you can download the latest file from AGI using the following code:

Copy

CentralBodiesFacet.GetFromContext().Earth.OrientationParameters = EarthOrientationParametersFile.DownloadData();

GPS Data

Several data files are used with the Navigation Accuracy Library to compute information about GPS satellites. These data files are available for download from AGI. Consult the documentation for each class for more information about each of these data files, and how to load and use the data in DME Component Libraries.

GpsDataFile - available from https://ftp.agi.com/pub/Catalog/Almanacs/SEM/GPSData.txt
PerformanceAssessmentFile - available from https://ftp.agi.com/pub/Catalog/PAF/
SatelliteOutageFile - available from https://ftp.agi.com/pub/Catalog/SOF/
SemAlmanac - available from https://ftp.agi.com/pub/Catalog/Almanacs/SEM/

Solar Geophysical Data (Space Weather)

Some atmospheric density models in the Orbit Propagation Library use data about solar radiation and geomagnetic flux indices. This data can be loaded from data files obtained from CSSI at http://celestrak.com/spacedata/. To load this data into DME Component Libraries, construct a CssiSolarGeophysicalData object using one of the static methods on the class, then use that object to construct the desired density model.

JPL Planetary Ephemeris (JPLDE)

JPL Planetary Ephemeris files can be loaded to provide a more accurate model of the position of a CentralBody in DME Component Libraries. In particular, the Sun, Moon, planets, and Pluto can be located more accurately using this model. Ceres, Vesta, and the planetary moons require use of the JPL SPICE ephemeris system to locate them more accurately.

These data files can be downloaded from: https://ftp.agi.com/pub/STKData/Astro/PlanetEphem/lendian/. Each type of file has a corresponding class that can read the data. The most current file at the time of writing is DE 440, which can be loaded with the JplDE440 class. Once loaded, the data can be used for the positions of the centers of mass of the central bodies in the CentralBodiesFacet by calling JplDEUseForCentralBodyPositions.

Copy

// Load a JplDE file using a string that represents the JplDE file
JplDE440 jplde = new JplDE440(Path.Combine(dataPath, "plneph.440"));

// Use the JplDE data in a CentralBodiesFacet
CentralBodiesFacet centralBodies = CentralBodiesFacet.GetFromContext();
jplde.UseForCentralBodyPositions(centralBodies);

// Optional - use the JplDE data for the Lunar fixed frame
MoonCentralBody moon = centralBodies.Moon;
moon.FixedFrame = jplde.GetMoonFixedFrame();

JPL SPICE Ephemeris

JPL SPICE files can be loaded to provide a more accurate model of some planetary moons, Ceres, and Vesta. They also allow the centers of mass of the outer planets to be modeled more accurately with respect to their planetary system barycenters. (JPLDE assumes that all planets other than Earth are located at their planetary system barycenters.)

The .bsp file format is used to locate these central bodies. Detailed instructions for how to acquire the necessary .bsp files are given in the documentation for JplSpkEphemerisProvider and its derived classes. The following code samples assume that the files have already been downloaded:

Setting up the Solar System using the Planetary Data Supplement: Use ModelSolarSystemUsingPlanetaryDataSupplement to set up the Solar System.

Copy

// Create JplSpkEphemerisProvider types that allow the Solar System to be modeled.
// Each path should point to the corresponding .bsp file (e.g. planetsPath points to planets.bsp).
var planetsEphemerisProvider = new PlanetsBspEphemerisProvider(planetsPath);
var asteroidsEphemerisProvider = new AsteroidsBspEphemerisProvider(asteroidsPath);
var marsEphemerisProvider = new MarsBspEphemerisProvider(marsPath, planetsEphemerisProvider.MarsSystemBarycenter);
var jupiterEphemerisProvider = new JupiterBspEphemerisProvider(jupiterPath, planetsEphemerisProvider.JupiterSystemBarycenter);
var saturnEphemerisProvider = new SaturnBspEphemerisProvider(saturnPath, planetsEphemerisProvider.SaturnSystemBarycenter);
var uranusEphemerisProvider = new UranusBspEphemerisProvider(uranusPath, planetsEphemerisProvider.UranusSystemBarycenter);
var neptuneEphemerisProvider = new NeptuneBspEphemerisProvider(neptunePath, planetsEphemerisProvider.NeptuneSystemBarycenter);
var plutoEphemerisProvider = new PlutoBspEphemerisProvider(plutoPath, planetsEphemerisProvider.PlutoSystemBarycenter);

// Get the current CentralBodiesFacet to allow it to be updated to use the
// more accurate ephemeris data.
var centralBodiesFacet = CentralBodiesFacet.GetFromContext();

// Update the CentralBodiesFacet so that its CentralBodies and Barycenters
// use more accurate CenterOfMassPoint locations.
JplSpkEphemerisProvider.ModelSolarSystemUsingPlanetaryDataSupplement(centralBodiesFacet,
                                                                     planetsEphemerisProvider,
                                                                     asteroidsEphemerisProvider,
                                                                     marsEphemerisProvider,
                                                                     jupiterEphemerisProvider,
                                                                     saturnEphemerisProvider,
                                                                     uranusEphemerisProvider,
                                                                     neptuneEphemerisProvider,
                                                                     plutoEphemerisProvider);

Setting up the Solar System using the Public JPL Data: Use ModelSolarSystemUsingPublicJplData to set up the Solar System.

Copy

// A JplDE instance (such as JplDE440) is used in conjunction with .bsp files to localize
// the Solar System using public JPL data. This path should point to a plneph.440 file.
var jplDe440 = new JplDE440(jplDE440Path);

// Create JplSpkEphemerisProvider types that allow the Solar System to be modeled.
// Each path should point to the corresponding .bsp file (e.g. jup365Path points to jup365.bsp).
var ceresEphemerisProvider = new CeresBspEphemerisProvider(ceresPath, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Sun));
var vestaEphemerisProvider = new VestaBspEphemerisProvider(vestaPath, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Sun));
var mar097EphemerisProvider = new MarsBspEphemerisProvider(mar097Path, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Mars));
var jup365EphemerisProvider = new Jup365BspEphemerisProvider(jup365Path, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Jupiter));
var sat441EphemerisProvider = new Sat441BspEphemerisProvider(sat441Path, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Saturn));
var ura111EphemerisProvider = new Ura111BspEphemerisProvider(ura111Path, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Uranus));
var nep097EphemerisProvider = new Nep097BspEphemerisProvider(nep097Path, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Neptune));
var plu058EphemerisProvider = new Plu058BspEphemerisProvider(plu058Path, jplDe440.GetCenterOfMassPoint(JplDECentralBody.Pluto));

// Get the current CentralBodiesFacet to allow it to be updated to use the
// more accurate ephemeris data.
var centralBodiesFacet = CentralBodiesFacet.GetFromContext();

// Update the CentralBodiesFacet so that its CentralBodies and Barycenters
// use more accurate CenterOfMassPoint locations.
JplSpkEphemerisProvider.ModelSolarSystemUsingPublicJplData(centralBodiesFacet,
                                                           jplDe440,
                                                           ceresEphemerisProvider,
                                                           vestaEphemerisProvider,
                                                           mar097EphemerisProvider,
                                                           jup365EphemerisProvider,
                                                           sat441EphemerisProvider,
                                                           ura111EphemerisProvider,
                                                           nep097EphemerisProvider,
                                                           plu058EphemerisProvider);

Manually read SPICE files to locate celestial bodies: Use GetTargetPoint to create Point objects that represent the position of one celestial body with respect to another celestial body or barycenter. The method GetNaifIdsOfAvailableTargetPointsAndCenterPoints can be used to determine which celestial bodies and barycenters are available in a given SPICE file.

Copy

// The planets.bsp file is read manually to illustrate how
// to manually read .bsp files using the JplSpkFile type.
var planetsBspFile = new JplSpkFile(planetsPath);

// All of the CentralBodies available in planets.bsp are ultimately defined with
// respect to the Solar System barycenter, the net center of mass of all of the
// Solar System bodies.
Point solarSystemBarycenter = CentralBodiesFacet.GetFromContext().SolarSystemBarycenter.CenterOfMassPoint;

// Integer NAIF ID codes are used to get target points with respect to center points.
// https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/req/naif_ids.html
// is a good reference for how JPL defines CentralBodies and other points as NAIF ID codes.

// In particular, the NAIF ID code 10 represents the Sun (which technically orbits the Solar
// System barycenter), and the NAIF ID code 0 represents the Solar System barycenter.
Point sunPoint = planetsBspFile.GetTargetPoint(10, 0, solarSystemBarycenter);

// NAIF ID codes 1 and 2 represent the Mercury and Venus system barycenters. Mercury and Venus
// do not have any moons, so their system barycenters are co-located with their centers of
// mass. Thus, Mercury and Venus are modeled as orbiting the Solar System barycenter directly.
Point mercuryPoint = planetsBspFile.GetTargetPoint(1, 0, solarSystemBarycenter);
Point venusPoint = planetsBspFile.GetTargetPoint(2, 0, solarSystemBarycenter);

// NAIF ID code 3 represents the Earth-Moon barycenter, which is the center of mass of the Earth-Moon
// system. This is modeled as orbiting the Solar System barycenter. The Earth (NAIF ID code 399)
// and the Moon (NAIF ID code 301) are modeled as orbiting the Earth-Moon barycenter.
Point earthMoonBarycenter = planetsBspFile.GetTargetPoint(3, 0, solarSystemBarycenter);
Point earthPoint = planetsBspFile.GetTargetPoint(399, 3, earthMoonBarycenter);
Point moonPoint = planetsBspFile.GetTargetPoint(301, 3, earthMoonBarycenter);

// NAIF ID code 4 represents the Mars system barycenter. Since the Martian moons Phobos and Deimos
// have such low masses, this is within centimeters of the location of the center of mass of Mars
// itself (NAIF ID code 499). Thus, the Mars system barycenter point can simply be cloned to get
// a point for Mars itself.
Point marsSystemBarycenter = planetsBspFile.GetTargetPoint(4, 0, solarSystemBarycenter);
Point marsPoint = (Point)marsSystemBarycenter.Clone(new CopyContext());

// NAIF ID code 5 represents the Jupiter system barycenter. Io, Europa, Ganymede, and Callisto
// have substantial enough mass compared to Jupiter that Jupiter itself (NAIF ID code 599) must be
// modeled as orbiting the Jupiter system barycenter in order to correctly define its position.
Point jupiterSystemBarycenter = planetsBspFile.GetTargetPoint(5, 0, solarSystemBarycenter);
Point jupiterPoint = planetsBspFile.GetTargetPoint(599, 5, jupiterSystemBarycenter);

// NAIF ID code 6 represents the Saturn system barycenter. Titan and the smaller moons of Saturn
// have substantial enough mass compared to Saturn that Saturn itself (NAIF ID code 699) must be
// modeled as orbiting the Saturn system barycenter in order to correctly define its position.
Point saturnSystemBarycenter = planetsBspFile.GetTargetPoint(6, 0, solarSystemBarycenter);
Point saturnPoint = planetsBspFile.GetTargetPoint(699, 6, saturnSystemBarycenter);

// NAIF ID code 7 represents the Uranus system barycenter. The major moons of Uranus
// have substantial enough mass compared to Uranus that Uranus itself (NAIF ID code 799) must be
// modeled as orbiting the Uranus system barycenter in order to correctly define its position.
Point uranusSystemBarycenter = planetsBspFile.GetTargetPoint(7, 0, solarSystemBarycenter);
Point uranusPoint = planetsBspFile.GetTargetPoint(799, 7, uranusSystemBarycenter);

// NAIF ID code 8 represents the Neptune system barycenter. Triton and the smaller moons of Neptune
// have substantial enough mass compared to Neptune that Neptune itself (NAIF ID code 899) must be
// modeled as orbiting the Neptune system barycenter in order to correctly define its position.
Point neptuneSystemBarycenter = planetsBspFile.GetTargetPoint(8, 0, solarSystemBarycenter);
Point neptunePoint = planetsBspFile.GetTargetPoint(899, 8, neptuneSystemBarycenter);

// NAIF ID code 9 represents the Pluto system barycenter. Charon has substantial enough mass
// compared to Pluto that Pluto itself (NAIF ID code 999) must be modeled as orbiting the
// Pluto system barycenter in order to correctly define its position.
Point plutoSystemBarycenter = planetsBspFile.GetTargetPoint(9, 0, solarSystemBarycenter);
Point plutoPoint = planetsBspFile.GetTargetPoint(999, 9, plutoSystemBarycenter);

// The planetary moons (besides the Moon of Earth) are in separate .bsp files and their positions
// are defined in terms of the system barycenters. For example, jupiter.bsp can be manually read
// to get the positions of Io, Europa, Ganymede, and Callisto with respect to the Jupiter system
// barycenter Point that was defined earlier.
var jupiterBspFile = new JplSpkFile(jupiterPath);
Point ioPoint = jupiterBspFile.GetTargetPoint(501, 5, jupiterSystemBarycenter);
Point europaPoint = jupiterBspFile.GetTargetPoint(502, 5, jupiterSystemBarycenter);
Point ganymedePoint = jupiterBspFile.GetTargetPoint(503, 5, jupiterSystemBarycenter);
Point callistoPoint = jupiterBspFile.GetTargetPoint(504, 5, jupiterSystemBarycenter);

// Finally, Ceres, Vesta, and 28 other asteroids are defined in the asteroids.bsp file with respect
// to the Solar System barycenter.
var asteroidsBspFile = new JplSpkFile(asteroidsPath);
Point ceresPoint = asteroidsBspFile.GetTargetPoint(2000001, 0, solarSystemBarycenter);
Point vestaPoint = asteroidsBspFile.GetTargetPoint(2000004, 0, solarSystemBarycenter);
Point erosPoint = asteroidsBspFile.GetTargetPoint(2000433, 0, solarSystemBarycenter);