Calculation of ephemerides from data stored in XEPH files. More...

#include <EphemerisFile.h>

Public Member Functions
	Handle (const EphemerisFile &parent, const IsoString &object, const IsoString &origin=IsoString())

	Handle (const Handle &x)

	Handle (Handle &&x)

virtual	~Handle ()

const Optional< double > &	B_V () const

void	ComputeFirstDerivative (Vector &v, TimePoint t)

void	ComputeSecondDerivative (Vector &a, TimePoint t)

void	ComputeState (Vector &p, TimePoint t)

void	ComputeState (Vector &p, Vector &v, TimePoint t)

const Optional< double > &	D () const

TimePoint	EndTime (int i=0) const

Vector	FirstDerivative (TimePoint t)

const Optional< double > &	G () const

const Optional< double > &	H () const

bool	HasDerivative () const

const IsoString &	ObjectId () const

const String &	ObjectName () const

Handle &	operator= (const Handle &x)

Handle &	operator= (Handle &&x)

const IsoString &	OriginId () const

const EphemerisFile &	ParentFile () const

Vector	SecondDerivative (TimePoint t)

TimePoint	StartTime (int i=0) const

Vector	StateVector (TimePoint t)

MultiVector	StateVectors (TimePoint t)

Detailed Description

This subclass provides access to ephemeris data for a specific object available in an ephemeris file. It can perform basic ephemeris calculations, including state vectors and its first derivatives (such as position and velocity), and performs all the low-level file seek and read operations transparently and efficiently.

Data stored in an XEPH ephemeris file generates rectangular coordinates referred to the axes of the International Celestial Reference System (ICRS/J2000.0). Positions are given in au and velocities in au/day for all solar system objects, except planetocentric coordinates of natural satellites, including the geocentric Moon, for which positions and velocities are given in kilometers and km/day, respectively. Angles (nutations and librations) are given in radians, and time differences (such as TT-TDB) in seconds.

For performance reasons, this class is not thread-safe. However, as far as a given instance is never used concurrently from two or more threads, multiple instances of this class can be used from different running threads, including instances constructed to calculate ephemerides for the same object. This allows for the implementation of performance-intensive, lock-free multithreaded ephemeris calculation tasks.

Definition at line 1674 of file EphemerisFile.h.

Constructor & Destructor Documentation

◆ Handle() [1/3]

pcl::EphemerisFile::Handle::Handle	(	const EphemerisFile &	parent,
		const IsoString &	object,
		const IsoString &	origin = `IsoString()`
	)

inline

Constructs a new Handle object.

Parameters

parent	Reference to an open EphemerisFile object providing access to an ephemeris data file in XEPH format.
object	The identifier or name of the object for which this instance will compute ephemerides.
origin	The identifier of the origin of coordinates. If an empty string is specified (which is the default parameter value), this object will be created for the first occurrence of ephemeris data available for object in the parent file, irrespective of the origin. In such case, if parent is a standard fundamental ephemerides file, the origin is the solar system barycenter (identified as "SSB").

For a detailed description of object names and identifiers, see EphemerisFile::IsObjectAvailable().

If the specified parent ephemeris file is not open, or if no ephemeris data are available for the specified object and origin in the parent ephemeris file, this constructor will throw an Error exception.

Definition at line 1704 of file EphemerisFile.h.

◆ Handle() [2/3]

pcl::EphemerisFile::Handle::Handle ( const Handle & x )

inline

Copy constructor.

Definition at line 1716 of file EphemerisFile.h.

◆ Handle() [3/3]

pcl::EphemerisFile::Handle::Handle ( Handle && x )

inline

Move constructor.

Definition at line 1730 of file EphemerisFile.h.

◆ ~Handle()

virtual pcl::EphemerisFile::Handle::~Handle ( )

inlinevirtual

Virtual destructor.

Definition at line 1743 of file EphemerisFile.h.

Member Function Documentation

◆ B_V()

const Optional<double>& pcl::EphemerisFile::Handle::B_V ( ) const

inline

Color index B-V, in magnitudes.

Definition at line 2142 of file EphemerisFile.h.

◆ ComputeFirstDerivative()

void pcl::EphemerisFile::Handle::ComputeFirstDerivative	(	Vector &	v,
		TimePoint	t
	)

inline

Computes the first derivative of the state vector for the specified time point t.

Parameters

[out]	v	Reference to a vector where the components of the computed first derivative will be stored.
	t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Rectangular coordinates for velocity are provided in au/day, except for the geocentric Moon, for which velocity is provided in km/day.

Angle variations are provided in radians/day.

Time difference variations are provided in seconds/day.

The reference system is ICRS/J2000.0.

If the parent ephemeris file provides Chebyshev expansions of state vector derivatives for the object being calculated, the components of v will be calculated directly from these expansions. Otherwise the components of v will be approximated by numerical differentiation of the Chebyshev expansions for state vectors.

If t is either an invalid (uninitialized) TimePoint instance, or a time point outside the time span available from the parent ephemeris file, this member function throws an Error exception.

Definition at line 1882 of file EphemerisFile.h.

◆ ComputeSecondDerivative()

void pcl::EphemerisFile::Handle::ComputeSecondDerivative	(	Vector &	a,
		TimePoint	t
	)

inline

Computes the second derivative of the state vector for the specified time point t.

Parameters

[out]	a	Reference to a vector where the components of the computed second derivative will be stored.
	t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Rectangular coordinates for acceleration are provided in au/day^2, except for the geocentric Moon, for which acceleration is provided in km/day^2.

Angular second derivatives are provided in radians/day^2.

Time second derivatives are provided in seconds/day^2.

The reference system is ICRS/J2000.0.

The components of the second derivative will be approximated by numerical differentiation of the Chebyshev expansions for the first derivative. The latter can be either provided directly by the parent ephemeris file, or also approximated by numerical differentiation.

If t is either an invalid (uninitialized) TimePoint instance, or a time point outside the time span available from the parent ephemeris file, this member function throws an Error exception.

Definition at line 1926 of file EphemerisFile.h.

◆ ComputeState() [1/2]

void pcl::EphemerisFile::Handle::ComputeState	(	Vector &	p,
		TimePoint	t
	)

inline

Computes a state vector for the specified time point t.

Parameters

[out]	p	Reference to a vector where the components of the computed state will be stored.
	t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Rectangular coordinates for position are provided in au, except for the geocentric Moon, for which positions are provided in km.

Angles are provided in radians.

TT-TDB differences are provided in seconds.

The reference system is ICRS/J2000.0.

If t is either an invalid (uninitialized) TimePoint instance, or a time point outside the time span available from the parent ephemeris file, this member function throws an Error exception.

Definition at line 1805 of file EphemerisFile.h.

◆ ComputeState() [2/2]

void pcl::EphemerisFile::Handle::ComputeState	(	Vector &	p,
		Vector &	v,
		TimePoint	t
	)

inline

Computes a state vector and its first derivative for the specified time point t.

Parameters

[out]	p	Reference to a vector where the components of the computed state will be stored.
[out]	v	Reference to a vector where the components of the computed first derivative will be stored.
	t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Rectangular coordinates for position and velocity are provided in au and au/day, respectively, except for the geocentric Moon, for which position and velocity are provided in km and km/day, respectively.

Angles and their variations are provided in radians and radians/day.

Time differences (such as TT-TDB) and their variations are provided in seconds and seconds/day.

The reference system is ICRS/J2000.0.

If the parent ephemeris file provides Chebyshev expansions of state vector derivatives for the object being calculated, the components of v will be calculated directly from these expansions. Otherwise the components of v will be approximated by numerical differentiation of the Chebyshev expansions for state vectors.

If t is either an invalid (uninitialized) TimePoint instance, or a time point outside the time span available from the parent ephemeris file, this member function throws an Error exception.

Definition at line 1846 of file EphemerisFile.h.

◆ D()

const Optional<double>& pcl::EphemerisFile::Handle::D ( ) const

inline

Diameter of the object in km. When available, this is normally an IRAS diameter for an asteroid.

Definition at line 2151 of file EphemerisFile.h.

◆ EndTime()

TimePoint pcl::EphemerisFile::Handle::EndTime ( int i = 0 ) const

inline

Returns the upper bound of the time span for which this instance can calculate ephemerides using the ephemeris data already available. If a time point outside this span is requested, new file seek and read operations must be performed.

Parameters

i	Expansion index: 0 to select function values (such as position), 1 to select function derivatives (such as velocity).

Definition at line 2093 of file EphemerisFile.h.

References pcl::Range().

◆ FirstDerivative()

Vector pcl::EphemerisFile::Handle::FirstDerivative ( TimePoint t )

inline

Computes the first derivative of a state vector for the specified time point t.

Parameters

t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Returns the computed first derivative vector.

See ComputeFirstDerivative( Vector&, TimePoint ) for complete information.

Definition at line 1999 of file EphemerisFile.h.

◆ G()

const Optional<double>& pcl::EphemerisFile::Handle::G ( ) const

inline

Slope parameter. See H() for references.

Definition at line 2134 of file EphemerisFile.h.

◆ H()

const Optional<double>& pcl::EphemerisFile::Handle::H ( ) const

inline

Returns the absolute magnitude of the object. H is the visual magnitude of the object as seen at 1 au of the Earth, 1 au from the Sun, and with a phase angle of 0 degrees.

References

E. Bowell et al., Asteroids II, R. P. Binzel et al. (eds.), The University of Arizona Press, Tucson, 1989, pp. 549-554.

Urban, Sean E., Kenneth Seidelmann, P., ed. (2013), The Explanatory Supplement to the Astronomical Almanac 3rd Edition, Section 10.4.3.

Definition at line 2126 of file EphemerisFile.h.

◆ HasDerivative()

bool pcl::EphemerisFile::Handle::HasDerivative ( ) const

inline

Returns true iff the parent ephemeris file provides Chebyshev expansions of state vector derivatives for the object for which this handle computes ephemerides.

When no expansions for derivatives are available, derivatives are approximated by numerical differentiation of the Chebyshev expansions for state vectors.

Definition at line 2107 of file EphemerisFile.h.

◆ ObjectId()

const IsoString& pcl::EphemerisFile::Handle::ObjectId ( ) const

inline

Returns the unique identifier of the object for which this handle can compute ephemerides.

Definition at line 2039 of file EphemerisFile.h.

◆ ObjectName()

const String& pcl::EphemerisFile::Handle::ObjectName ( ) const

inline

Returns the name of the object for which this handle can compute ephemerides. The returned value can be an empty string if no information about the object name is available in the parent ephemeris file.

Definition at line 2063 of file EphemerisFile.h.

◆ operator=() [1/2]

Handle& pcl::EphemerisFile::Handle::operator= ( const Handle & x )

inline

Copy assignment operator. Returns a reference to this object.

Definition at line 1752 of file EphemerisFile.h.

◆ operator=() [2/2]

Handle& pcl::EphemerisFile::Handle::operator= ( Handle && x )

inline

Move assignment operator. Returns a reference to this object.

Definition at line 1769 of file EphemerisFile.h.

◆ OriginId()

const IsoString& pcl::EphemerisFile::Handle::OriginId ( ) const

inline

Returns the unique identifier of the origin of the coordinates computed by this object. For example, if this member function returns "Ea" or "Sn", the computed coordinates are geocentric or heliocentric, respectively. If this function returns "SSB", the origin of coordinates is the solar system barycenter. This happens, for example, with all standard XEPH files providing fundamental ephemerides.

Definition at line 2052 of file EphemerisFile.h.

◆ ParentFile()

const EphemerisFile& pcl::EphemerisFile::Handle::ParentFile ( ) const

inline

Returns a reference to the parent ephemeris file object. The parent object was specified upon construction.

Definition at line 2030 of file EphemerisFile.h.

◆ SecondDerivative()

Vector pcl::EphemerisFile::Handle::SecondDerivative ( TimePoint t )

inline

Computes the second derivative of a state vector for the specified time point t.

Parameters

t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Returns the computed second derivative vector.

See ComputeSecondDerivative( Vector&, TimePoint ) for complete information.

Definition at line 2019 of file EphemerisFile.h.

◆ StartTime()

TimePoint pcl::EphemerisFile::Handle::StartTime ( int i = 0 ) const

inline

Returns the lower bound of the time span for which this instance can calculate ephemerides using the ephemeris data already available. If a time point outside this span is requested, new file seek and read operations must be performed.

Parameters

i	Expansion index: 0 to select function values (such as position), 1 to select function derivatives (such as velocity).

Definition at line 2078 of file EphemerisFile.h.

References pcl::Range().

◆ StateVector()

Vector pcl::EphemerisFile::Handle::StateVector ( TimePoint t )

inline

Computes a state vector for the specified time point t.

Parameters

t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Returns the computed state function value.

See ComputeState( Vector&, TimePoint ) for complete information.

Definition at line 1958 of file EphemerisFile.h.

◆ StateVectors()

MultiVector pcl::EphemerisFile::Handle::StateVectors ( TimePoint t )

inline

Computes a state vector and its first derivative for the specified time point t.

Parameters

t	The requested time point in the TDB time scale (rigorously, this is Teph as defined by JPL, but is equivalent to TDB or TT for all practical purposes).

Returns a two-component multivector, where the first component vector is the state function's value and the second is its first derivative.

See ComputeState( Vector&, Vector&, TimePoint ) for complete information.

Definition at line 1979 of file EphemerisFile.h.

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

EphemerisFile.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Handle() [1/3]

◆ Handle() [2/3]

◆ Handle() [3/3]

◆ ~Handle()

Member Function Documentation

◆ B_V()

◆ ComputeFirstDerivative()

◆ ComputeSecondDerivative()

◆ ComputeState() [1/2]

◆ ComputeState() [2/2]

◆ D()

◆ EndTime()

◆ FirstDerivative()

◆ G()

◆ H()

◆ HasDerivative()

◆ ObjectId()

◆ ObjectName()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ OriginId()

◆ ParentFile()

◆ SecondDerivative()

◆ StartTime()

◆ StateVector()

◆ StateVectors()