Detailed Description

Class SolarSystemEphemeris encapsulates the information in the JPL ephemeris file, header and data, reading and writing of both ASCII and binary files, as well as the computation of position and velocity of the sun, moon and planets, plus nutations and lunar librations and their rates. The user of this class should not have to read or write new files except either when the class is initially installed on a platform, or when a new ephemeris is obtained from JPL. Then procedure is first to download ASCII files for the desired ephemeris from the JPL ftp site at ftp://ssd.jpl.nasa.gov/pub/eph/planets. This consists of an ASCII header file (e.g. header.403) plus one or more ephemeris data files for the same ephemeris (e.g. ascp1975.403, ascp2000.403 and ascp2025.403 - these files contain the complete "DE403" ephemeris covering years 1975 to 2025). The user should then use a conversion program (such as convertEphemeris in the gnsstk) to read these files and write out a single binary file for use in applications. Writing the binary file on the platform on which it is going to be used avoids potential problems with platform dependencies. The gnsstk also includes a test program, testEphemeris, which will read a test file (also at the JPL ftp site) and compute several states, comparing them with JPL-generated 'truth' values; this will validate the generated binary file. To make use of this class and the generated binary file, the programmer simply instantiates a SolarSystemEphemeris object, calls initializeWithBinaryFile(file) once, passing it the name of the binary file, then calling relativeInertialPositionVelocity() any number of times, passing it the time and Planet of interest. Time for this class is always Barycentric Dynamic Time (TDB), always as MJD.

Definition at line 96 of file SolarSystemEphemeris.hpp.

#include <SolarSystemEphemeris.hpp>

Inheritance diagram for gnsstk::SolarSystemEphemeris:

[legend]

Public Types
enum	Planet { idNone = 0, idMercury, idVenus, idEarth, idMars, idJupiter, idSaturn, idUranus, idNeptune, idPluto, idMoon, idSun, idSolarSystemBarycenter, idEarthMoonBarycenter, idNutations, idLibrations }
	These are indexes used by the caller of inertialPositionVelocity(). More...

enum	ReturnValue { retOK = 0, retEarly = -1, retLate = -2, retStrm = -3, retEphN = -4 }
	Return values. More...

Public Member Functions
double	AU ()

void	clearStorage ()

double	endTimeMJD () const
	Return the MJD of end time of the data (system TDB) More...

int	EphNumber () const

double	getConstant (const std::string &name)

int	initializeWithBinaryFile (const std::string &filename)

double	ratioEarthToMoonMass ()
	Return the Earth-to-Moon mass ratio. More...

double	ratioSunToEarthMass ()
	Return the Sun-to-Earth mass ratio. More...

int	readASCIIdata (const std::string &filename)

int	readASCIIdata (std::vector< std::string > &filenames)

void	readASCIIheader (const std::string &filename)

int	readBinaryFile (const std::string &filename)

void	relativeInertialPositionVelocity (double MJD, Planet target, Planet center, double PV[6], bool kilometers=true)

	SolarSystemEphemeris ()

double	startTimeMJD () const
	Return the MJD of start time of the data (system TDB) More...

int	writeASCIIdata (std::ostream &os)

int	writeASCIIheader (std::ostream &os)

int	writeBinaryFile (const std::string &filename)

Private Types
enum	computeID { NONE = -1, MERCURY, VENUS, EMBARY, MARS, JUPITER, SATURN, URANUS, NEPTUNE, PLUTO, MOON, SUN, NUTATIONS, LIBRATIONS }

Private Member Functions
void	inertialPositionVelocity (double MJD, computeID which, double PV[6])

void	readBinary (char *ptr, size_t size)

int	readBinaryData (bool save)

void	readBinaryHeader (const std::string &filename)

int	readBinaryRecord (std::vector< double > &data_vector)

int	seekToJD (double JD)

void	writeBinary (std::ofstream &strm, const char *ptr, size_t size)

Private Attributes
int	c_ncoeff [13]
	number of coefficients per component for each planet More...

int	c_nsets [13]
	number of sets of coefficients for each planet More...

int	c_offset [13]

std::vector< double >	coefficients

std::map< std::string, double >	constants

double	endJD
	JD of the end of the last record in the file. More...

int	EphemerisNumber

std::map< double, long >	fileposMap

double	interval
	number of days covered by each block of coeff.s More...

std::ifstream	istrm
	input stream for binary files More...

std::string	label [3]
	lines under group 1010 More...

int	Ncoeff

int	Nconst
	number of constants in the header (see map constants) More...

double	startJD
	JD of the start of the first record in the file. More...

std::map< double, std::vector< double > >	store

Member Enumeration Documentation

◆ computeID

enum gnsstk::SolarSystemEphemeris::computeID

private

These are indexes used in the actual computation, and correspond to indexes in the ephemeris file; for example computation for the SUN is done using c_offset[SUN], c_ncoeff[SUN] and c_nsets[SUN].

Enumerator
NONE	-1 Place holder
MERCURY	0 Mercury
VENUS	1 Venus
EMBARY	2 Earth-Moon barycenter
MARS	3 Mars
JUPITER	4 Jupiter
SATURN	5 Saturn
URANUS	6 Uranus
NEPTUNE	7 Neptune
PLUTO	8 Pluto
MOON	9 Moon (Geocentric coordinates)
SUN	10 Sun
NUTATIONS	11 Nutations (psi, epsilon and their rates)
LIBRATIONS	12 Lunar Librations (3 euler angles)

Definition at line 412 of file SolarSystemEphemeris.hpp.

◆ Planet

enum gnsstk::SolarSystemEphemeris::Planet

These are indexes used by the caller of inertialPositionVelocity().

Enumerator
idNone	0 place holder
idMercury	1 Mercury
idVenus	2 Venus
idEarth	3 Earth
idMars	4 Mars
idJupiter	5 Jupiter
idSaturn	6 Saturn
idUranus	7 Uranus
idNeptune	8 Neptune
idPluto	9 Pluto
idMoon	10 Moon (Geocentric coordinates)
idSun	11 Sun
idSolarSystemBarycenter	12 Solar system barycenter
idEarthMoonBarycenter	13 Earth-moon barycenter
idNutations	14 Nutations (psi, epsilon and rates)
idLibrations	15 Lunar Librations (3 euler angles)

Definition at line 110 of file SolarSystemEphemeris.hpp.

◆ ReturnValue

enum gnsstk::SolarSystemEphemeris::ReturnValue

Return values.

Enumerator
retOK	0 ok
retEarly	-1 out of range : input time is before first time in file
retLate	-2 out of range : input time is after last time in file
retStrm	-3 stream is not open and good, or EOF found prematurely
retEphN	-4 EphemerisNumber is not defined

Definition at line 100 of file SolarSystemEphemeris.hpp.

Constructor & Destructor Documentation

◆ SolarSystemEphemeris()

gnsstk::SolarSystemEphemeris::SolarSystemEphemeris ( )

inline

Constructor. Set EphemerisNumber to -1 to indicate that nothing has been read yet.

Definition at line 136 of file SolarSystemEphemeris.hpp.

Member Function Documentation

◆ AU()

double gnsstk::SolarSystemEphemeris::AU ( )

inline

Return the value of 1 AU (Astronomical Unit) in km. If the file header has not been read, return -1.0.

Returns: the value of 1 AU in km; return -1 if ephemeris has not been initialized.

Definition at line 289 of file SolarSystemEphemeris.hpp.

◆ clearStorage()

void gnsstk::SolarSystemEphemeris::clearStorage ( )

inline

clear the store map containing all the data read by readASCIIdata() or readBinaryData(true).

Definition at line 217 of file SolarSystemEphemeris.hpp.

◆ endTimeMJD()

double gnsstk::SolarSystemEphemeris::endTimeMJD ( ) const

inline

Return the MJD of end time of the data (system TDB)

Definition at line 342 of file SolarSystemEphemeris.hpp.

◆ EphNumber()

int gnsstk::SolarSystemEphemeris::EphNumber ( ) const

inline

Return the ephemeris number.

Returns: the 'DE' ephemeris number, e.g. 403, or -1 if ephemeris has not been initialized.

Definition at line 303 of file SolarSystemEphemeris.hpp.

◆ getConstant()

double gnsstk::SolarSystemEphemeris::getConstant ( const std::string & name )

inline

Returns: the value of the contant with the given name. If the header has not been read, return -1. Return zero if the constant is not found.

Definition at line 310 of file SolarSystemEphemeris.hpp.

◆ inertialPositionVelocity()

void gnsstk::SolarSystemEphemeris::inertialPositionVelocity	(	double	MJD,
		SolarSystemEphemeris::computeID	which,
		double	PV[6]
	)

private

Compute inertial position and velocity of given body at given time, relative to the solar system barycenter, using the current coefficient array. NB caller MUST call seekToJD(time) BEFORE calling this. On successful return, PV[0-2] contains the three position components, in km, and PV[3-5] the velocity components in km/day (for regular bodies), relative to the solar system barycenter, except for the moon, which is relative to Earth. For nutations and librations the units are radians and radians/day; nutations (components 0-3 only) are longitude and obliquity, and librations are the three euler angles.

Parameters

MJD	time (Modified Julian Date) of interest (system TDB).
which	computeID of the body of interest.
PV	double(6) array containing the inertial position and velocity relative to the solar system barycenter.

Definition at line 1563 of file SolarSystemEphemeris.cpp.

◆ initializeWithBinaryFile()

int gnsstk::SolarSystemEphemeris::initializeWithBinaryFile ( const std::string & filename )

Open the given binary file, read the header and prepare for reading data records at random using seekToJD() and computing positions and velocities with inertialPositionVelocity(). Does not store the data.

Parameters

filename name of binary file to be read.

Returns: 0 success, -3 input stream is not open or not valid -4 header has not yet been read.

Exceptions

Exception if a gap in time is found between consecutive records.

Definition at line 874 of file SolarSystemEphemeris.cpp.

◆ ratioEarthToMoonMass()

double gnsstk::SolarSystemEphemeris::ratioEarthToMoonMass ( )

inline

Return the Earth-to-Moon mass ratio.

Definition at line 324 of file SolarSystemEphemeris.hpp.

◆ ratioSunToEarthMass()

double gnsstk::SolarSystemEphemeris::ratioSunToEarthMass ( )

inline

Return the Sun-to-Earth mass ratio.

Definition at line 330 of file SolarSystemEphemeris.hpp.

◆ readASCIIdata() [1/2]

int gnsstk::SolarSystemEphemeris::readASCIIdata ( const std::string & filename )

Read only one ASCII data file. Also see the documentation for the other version of this routine.

Parameters

filename name of an ASCII data files (downloaded from JPL)

Returns: 0 ok, -1 if a stream error occurred, -4 header has not been read.

Exceptions

Exception	if the header has not yet been read.
Exception	if the file could not be opened.
Exception	if any record has a 'number of coefficients' that differs from the header value.

◆ readASCIIdata() [2/2]

int gnsstk::SolarSystemEphemeris::readASCIIdata ( std::vector< std::string > & filenames )

Read one or more ASCII data files. Call only after having read the header, and call only with data files for the same ephemeris as the header (the JPL files are named 'header.NNN' and 'ascSYYYY.NNN' where NNN is the ephemeris number (appears inside the header file, but not inside the data files), S is either 'p' or 'n' as the year is positive or negative (AD or BC), and YYYY is the year of the first record in the file.

Parameters

filenames vector containting the names of the ASCII data files (downloaded from JPL), in any order.

Returns: 0 ok, -1 if a stream error occurred.

Exceptions

Exception	if the header has not yet been read.
Exception	if any file could not be opened.
Exception	if any record in any file has a 'number of coefficients' that differs from the header value.

◆ readASCIIheader()

void gnsstk::SolarSystemEphemeris::readASCIIheader ( const std::string & filename )

Read the header from a JPL ASCII planetary ephemeris file. Note that this routine clears the 'store' map and defines the 'constants' hash. It also sets EphemerisNumber to the constant "DENUM" if successful.

Parameters

filename the name of the ASCII header file.

Exceptions

Exception	if the file cannot be opened.
Exception	if the header ends prematurely or if it is not properly formatted.
Exception	if any stream error occurs.

Definition at line 86 of file SolarSystemEphemeris.cpp.

◆ readBinary()

void gnsstk::SolarSystemEphemeris::readBinary	(	char *	ptr,
		size_t	size
	)

private

Helper routine for binary reading.

Exceptions

Exception if there is any error or if EOF is found.

Definition at line 1131 of file SolarSystemEphemeris.cpp.

◆ readBinaryData()

int gnsstk::SolarSystemEphemeris::readBinaryData ( bool save )

private

Read data from a binary file, already opened by readBinaryHeader. Build the file position map, and store the first set of coefficients. If calling argument is true, save all the coefficient data in a map.

Parameters

save	if true, save all the data in store, else clear the store.

Returns: 0 success, -3 input stream is not open or not valid -4 header has not yet been read.

Exceptions

Exception if a gap in time is found between consecutive records.

Definition at line 1340 of file SolarSystemEphemeris.cpp.

◆ readBinaryFile()

int gnsstk::SolarSystemEphemeris::readBinaryFile ( const std::string & filename )

Read header and data from a binary file, storing ALL the data in store. For use with copying, merging or editing data files. Closes the stream before returning.

Parameters

filename name of binary file to be read.

Returns: 0 success, -3 input stream is not open or not valid -4 header has not yet been read.

Exceptions

Exception if a gap in time is found between consecutive records.

Definition at line 844 of file SolarSystemEphemeris.cpp.

◆ readBinaryHeader()

void gnsstk::SolarSystemEphemeris::readBinaryHeader ( const std::string & filename )

private

Read header from a binary file.

Parameters

filename name of binary file, probably written by writeBinaryFile().

Exceptions

Exception if read error or premature EOF if found.

Definition at line 1160 of file SolarSystemEphemeris.cpp.

◆ readBinaryRecord()

int gnsstk::SolarSystemEphemeris::readBinaryRecord ( std::vector< double > & data_vector )

private

Read a single binary record (not a header record) at the current file position, into the given vector. For use by readBinaryData() and seekToJD().

Parameters

data_vector vector<double> to hold coefficients.

Returns: 0 success, -2 EOF was reached -3 input stream is not open or not valid

Definition at line 1427 of file SolarSystemEphemeris.cpp.

◆ relativeInertialPositionVelocity()

void gnsstk::SolarSystemEphemeris::relativeInertialPositionVelocity	(	double	MJD,
		SolarSystemEphemeris::Planet	target,
		SolarSystemEphemeris::Planet	center,
		double	PV[6],
		bool	kilometers = `true`
	)

Compute inertial frame position and velocity of given 'target' body, relative to the 'center' body, at the given time. On successful return, PV contains position (in components 0-2) and velocity (components 3-5) (units: cf param km) for regular bodies; for nutations and librations the units are radians and radians/day; nutations (components 0-3 only) are longitude or psi (component 0) and obliquity or epsilon (component 1) and their rates (components 2,3); librations (components 0-5) are the 3 euler angles in radians and their rates in radians/day.

Parameters

MJD	time (Modified Julian Date) of interest, in TDB system.
target	Body for which position and velocity are to be computed.
center	Body relative to which the results apply. However, center may == SolarSystemEphemeris::None, in which case the results are relative to the solar system barycenter. If target == Nutations or Librations, center is ignored.
PV	Double array of length 6 containing output position and velocity components of target relative to center, in the order X,Y,Z,Vx,Vy,Vz. Units are determined by parameter km. If target == Nutations, PV contains 4 results, psi, eps, psi dot, eps dot in units radians and radians/day. If target == Librations, PV contains 3 euler angles in radians and their rates in radians/day.
kilometers	boolean: if true (default), units are km, km/day; else AU, AU/day (but not Nutations or Librations - see above).

Exceptions

Exception if given time is before the first record in the file, the given time is after the last record, or in a gap between records, the input stream is not open or not valid, or EOF was found prematurely, or the ephemeris is not initialized; most likely the last two happen because initializeWithBinaryFile() has not been called, or reading failed.

Definition at line 916 of file SolarSystemEphemeris.cpp.

◆ seekToJD()

int gnsstk::SolarSystemEphemeris::seekToJD ( double JD )

private

Search the data records of the file opened by initializeWithBinaryFile() and read the one whose time limits include the given time. May be called only after initializeWithBinaryFile().

Parameters

JD	the time (Julian Date) of interest

Returns: 0 success, or -1 given time is before the first record in the file, -2 given time is after the last record, or in a gap between records, -3 input stream is not open or not valid, or EOF was found prematurely, -4 ephemeris (binary file) is not initialized -3 or -4 => initializeWithBinaryFile() has not been called, or reading failed.

Definition at line 1489 of file SolarSystemEphemeris.cpp.

◆ startTimeMJD()

double gnsstk::SolarSystemEphemeris::startTimeMJD ( ) const

inline

Return the MJD of start time of the data (system TDB)

Definition at line 339 of file SolarSystemEphemeris.hpp.

◆ writeASCIIdata()

int gnsstk::SolarSystemEphemeris::writeASCIIdata ( std::ostream & os )

Write the stored data (ASCII) to an output stream NB. This routine does NOT clear the store - use clearStorage()

Exceptions

Exception if any stream error occurs

Returns: 0 success, -4 header has not yet been read.

Definition at line 625 of file SolarSystemEphemeris.cpp.

◆ writeASCIIheader()

int gnsstk::SolarSystemEphemeris::writeASCIIheader ( std::ostream & os )

Write the header (ASCII) to an output stream

Exceptions

Exception if any stream error occurs

Returns: 0 success, -4 header has not yet been read.

Definition at line 499 of file SolarSystemEphemeris.cpp.

◆ writeBinary()

void gnsstk::SolarSystemEphemeris::writeBinary	(	std::ofstream &	strm,
		const char *	ptr,
		size_t	size
	)

private

Helper routine for binary writing.

Exceptions

Exception if there is any stream error.

Definition at line 1101 of file SolarSystemEphemeris.cpp.

◆ writeBinaryFile()

int gnsstk::SolarSystemEphemeris::writeBinaryFile ( const std::string & filename )

Write the header and the stored data to a binary output file. NB. This routine does NOT clear the store - use clearStorage()

Parameters

filename name of binary file to be read.

Returns: 0 ok -4 if data has not been read into the object

Exceptions

Exception if any stream error occurs.

Definition at line 689 of file SolarSystemEphemeris.cpp.

Member Data Documentation

◆ c_ncoeff

int gnsstk::SolarSystemEphemeris::c_ncoeff[13]

private

number of coefficients per component for each planet

Definition at line 480 of file SolarSystemEphemeris.hpp.

◆ c_nsets

int gnsstk::SolarSystemEphemeris::c_nsets[13]

private

number of sets of coefficients for each planet

Definition at line 481 of file SolarSystemEphemeris.hpp.

◆ c_offset

int gnsstk::SolarSystemEphemeris::c_offset[13]

private

starting index in the coefficients array for each planet

Definition at line 477 of file SolarSystemEphemeris.hpp.

◆ coefficients

std::vector<double> gnsstk::SolarSystemEphemeris::coefficients

private

One complete data record (Ncoeff doubles) consisting of times and coefficients. seekToJD() stores the current record here, and inertialPositionVelocity() uses it.

Definition at line 534 of file SolarSystemEphemeris.hpp.

◆ constants

std::map<std::string, double> gnsstk::SolarSystemEphemeris::constants

private

Hash of labels and values of constants read from the header. This is taken directly from the JPL documentation:

The following is a partial list of constants found on the ephemeris file:
DENUM           Planetary ephemeris number.
LENUM           Lunar ephemeris number.
TDATEF, TDATEB  Dates of the Forward and Backward Integrations
CLIGHT          Speed of light (km/s).
AU              Number of kilometers per astronomical unit.
EMRAT           Earth-Moon mass ratio.
GMi             GM for ith planet [au**3/day**2].
GMB             GM for the Earth-Moon Barycenter [au**3/day**2].
GMS             Sun (= k**2) [au**3/day**2].
X1, ..., ZD9    Initial conditions for the numerical integration,
                  given at "JDEPOC", with respect to "CENTER".
JDEPOC          Epoch (JED) of initial conditions, normally JED 2440400.5.
CENTER          Reference center for the initial conditions.
                  (Sun: 11,  Solar System Barycenter: 12)
RADi            Radius of ith planet [km].
MA0001...MA0324 GM's of asteroid number 0001 ... 0234 [au**3/day**2].
PHASE           The phase angle of the moon's rotation.
LOVENO          The Love Number, k2, for the moon.
PHI, THT, PSI   Euler angles of the orientation of the lunar mantle.
OMEGAX, ...     Rotational velocities of the lunar mantle.
PHIC,THTC,PSIC  Euler angles of the orientation of the lunar core.
OMGCX, ...      Rotational velocities of the lunar core.

Definition at line 512 of file SolarSystemEphemeris.hpp.

◆ endJD

double gnsstk::SolarSystemEphemeris::endJD

private

JD of the end of the last record in the file.

Definition at line 475 of file SolarSystemEphemeris.hpp.

◆ EphemerisNumber

int gnsstk::SolarSystemEphemeris::EphemerisNumber

private

-1 if the header has not been filled; also, for binary file input, 0 if the file position map has not yet been filled; otherwise it equals the number JPL assigns the ephemeris, e.g. 403, 405, which is identical to constants["DENUM"].

Definition at line 464 of file SolarSystemEphemeris.hpp.

◆ fileposMap

std::map<double, long> gnsstk::SolarSystemEphemeris::fileposMap

private

Hash of start times (JD) and file positions. This object is filled by readBinaryData(), which is called by initializeWithBinaryFile(), and is used by seekToJD() to read records in random order.

Definition at line 527 of file SolarSystemEphemeris.hpp.

◆ interval

double gnsstk::SolarSystemEphemeris::interval

private

number of days covered by each block of coeff.s

Definition at line 476 of file SolarSystemEphemeris.hpp.

◆ istrm

std::ifstream gnsstk::SolarSystemEphemeris::istrm

private

input stream for binary files

Definition at line 453 of file SolarSystemEphemeris.hpp.

◆ label

std::string gnsstk::SolarSystemEphemeris::label[3]

private

lines under group 1010

Definition at line 473 of file SolarSystemEphemeris.hpp.

◆ Ncoeff

int gnsstk::SolarSystemEphemeris::Ncoeff

private

The number of coefficients in a single record. This will determine the binary record size

Definition at line 470 of file SolarSystemEphemeris.hpp.

◆ Nconst

int gnsstk::SolarSystemEphemeris::Nconst

private

number of constants in the header (see map constants)

Definition at line 472 of file SolarSystemEphemeris.hpp.

◆ startJD

double gnsstk::SolarSystemEphemeris::startJD

private

JD of the start of the first record in the file.

Definition at line 474 of file SolarSystemEphemeris.hpp.

◆ store

std::map<double, std::vector<double> > gnsstk::SolarSystemEphemeris::store

private

Hash of start times (JD) and coefficient arrays. This object is not intended to store the entire dataset, except temporarily for the purpose of reading/writing files, NOT for ephemeris computation.

Definition at line 520 of file SolarSystemEphemeris.hpp.

The documentation for this class was generated from the following files:

Detailed Description

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Member Enumeration Documentation

◆ computeID

◆ Planet

◆ ReturnValue

Constructor & Destructor Documentation

◆ SolarSystemEphemeris()

Member Function Documentation

◆ AU()

◆ clearStorage()

◆ endTimeMJD()

◆ EphNumber()

◆ getConstant()

◆ inertialPositionVelocity()

◆ initializeWithBinaryFile()

◆ ratioEarthToMoonMass()

◆ ratioSunToEarthMass()

◆ readASCIIdata() [1/2]

◆ readASCIIdata() [2/2]

◆ readASCIIheader()

◆ readBinary()

◆ readBinaryData()

◆ readBinaryFile()

◆ readBinaryHeader()

◆ readBinaryRecord()

◆ relativeInertialPositionVelocity()

◆ seekToJD()

◆ startTimeMJD()

◆ writeASCIIdata()

◆ writeASCIIheader()

◆ writeBinary()

◆ writeBinaryFile()

Member Data Documentation

◆ c_ncoeff

◆ c_nsets

◆ c_offset

◆ coefficients

◆ constants

◆ endJD

◆ EphemerisNumber

◆ fileposMap

◆ interval

◆ istrm

◆ label

◆ Ncoeff

◆ Nconst

◆ startJD

◆ store