agi.foundation.celestial

(agi.foundation.models-2024r3.jar)

Class JplDE

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.celestial.JplDE

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

JplDE200, JplDE403, JplDE405, JplDE421, JplDE430, JplDE440

public abstract class JplDE
extends DefinitionalObject

The common base for classes for loading and accessing JPL DE files.

JPL Planetary Ephemeris files can be downloaded from https://ftp.agi.com/pub/STKData/Astro/PlanetEphem/lendian/.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	JplDE(JplDE existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.
protected	JplDE(JplDEFile file) Initializes an instance using the specified JplDEFile instance.
protected	JplDE(StreamFactory streamFactory) Initializes a new instance with the specified stream factory.
protected	JplDE(String fileName) Initializes an instance using the specified JPL DE filename.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(DefinitionalObject other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(JplDE other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
Point	createEarthMoonBarycenterPoint() Creates a Point that represents the position of the Earth-Moon barycenter calculated from the data in this class.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
protected void	freezeAggregatedObjects() Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object.
JplDECenterOfMassPoint	getCenterOfMassPoint(JplDECentralBody centralBody) Gets a point which represents the center of mass of the given JplDECentralBody.
double	getEarthMoonMassRatio() Gets the ratio of the mass of the earth to the mass of the moon.
NutationModel	getEarthNutationModel() Creates a NutationModel which uses this JPL DE data for the nutation of the Earth.
JplDEFile	getFile() Gets the raw JPL DE file represented by this instance.
JulianDate	getFinalEpoch() Gets the last epoch for which ephemeris data is available.
double	getGravitationalParameter(JplDECentralBody centralBody) Gets the gravitational parameter of a central body in SI units (m^3/s^2).
double	getGravitationalParameterNative(JplDECentralBody centralBody) Gets the gravitational parameter of a central body in AU^3/day^2.
JulianDate	getInitialEpoch() Gets the first epoch for which ephemeris data is available.
double	getKilometersPerAstronomicalUnit() Gets the number of kilometers (km) in one astronomical unit (AU).
int	getLunarEphemerisNumber() Gets the number indicating the source of the data.
int	getPlanetaryEphemerisNumber() Gets the number indicating the source of the data.
double	getSpeedOfLight() Gets the speed of light in km/s.
List<String>	getTitles() Gets the collection of titles.
void	useForCentralBodyPositions(CentralBodiesFacet centralBodiesFacet) Uses this JPL DE data for the positions of the centers of mass of the central bodies in the specified CentralBodiesFacet instance.

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JplDE

protected JplDE(@Nonnull
                String fileName)

Initializes an instance using the specified JPL DE filename.

Parameters:

fileName - The full path and filename of the JPL DE file.

Throws:

ArgumentNullException - Thrown when fileName is null.

JplDE

protected JplDE(@Nonnull
                StreamFactory streamFactory)

Initializes a new instance with the specified stream factory.

The streams created by streamFactory must support seeking. This means that the streams must implement ISeekableStream or FileInputStream.

Parameters:

streamFactory - The factory to use to create streams to read the JPL DE data.

Throws:

ArgumentNullException - Thrown when streamFactory is null.

JplDE

protected JplDE(@Nonnull
                JplDEFile file)

Initializes an instance using the specified JplDEFile instance.

Parameters:

file - The JplDEFile instance to use.

Throws:

ArgumentNullException - Thrown when file is null.

JplDE

protected JplDE(@Nonnull
                JplDE existingInstance,
                @Nonnull
                CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

checkForSameDefinition

protected final boolean checkForSameDefinition(DefinitionalObject other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class DefinitionalObject

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected abstract boolean checkForSameDefinition(JplDE other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the JplDE.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

freezeAggregatedObjects

protected final void freezeAggregatedObjects()

Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object. Derived classes which contain additional aggregated objects MUST override this method, call the base implementation, and freeze aggregated objects introduced by the derived class. The objects that need to be frozen in this method are frequently created in this object's constructor and are not settable via properties.

Overrides:

freezeAggregatedObjects in class DefinitionalObject

getTitles

@Nonnull
public final List<String> getTitles()

Gets the collection of titles.

getPlanetaryEphemerisNumber

public final int getPlanetaryEphemerisNumber()

Gets the number indicating the source of the data. For example, '405' indicates the DE405 ephemerides.

getLunarEphemerisNumber

public final int getLunarEphemerisNumber()

Gets the number indicating the source of the data. For example, '405' indicates the DE405 ephemerides.

getSpeedOfLight

public final double getSpeedOfLight()

Gets the speed of light in km/s.

getKilometersPerAstronomicalUnit

public final double getKilometersPerAstronomicalUnit()

Gets the number of kilometers (km) in one astronomical unit (AU).

getEarthMoonMassRatio

public final double getEarthMoonMassRatio()

Gets the ratio of the mass of the earth to the mass of the moon.

getInitialEpoch

@Nonnull
public final JulianDate getInitialEpoch()

Gets the first epoch for which ephemeris data is available.

getFinalEpoch

@Nonnull
public final JulianDate getFinalEpoch()

Gets the last epoch for which ephemeris data is available.

getGravitationalParameterNative

public final double getGravitationalParameterNative(@Nonnull
                                                    JplDECentralBody centralBody)

Gets the gravitational parameter of a central body in AU^3/day^2.

Parameters:

centralBody - The central body for which to retrieve information.

Returns:

The gravitational parameter of the specified central body, in AU^3/day^2.

getGravitationalParameter

public final double getGravitationalParameter(@Nonnull
                                              JplDECentralBody centralBody)

Gets the gravitational parameter of a central body in SI units (m^3/s^2).

Parameters:

centralBody - The central body for which to retrieve information.

Returns:

The gravitational parameter of the specified central body, in m^3/s^2.

getCenterOfMassPoint

@Nonnull
public final JplDECenterOfMassPoint getCenterOfMassPoint(@Nonnull
                                                                   JplDECentralBody centralBody)

Gets a point which represents the center of mass of the given JplDECentralBody.

Parameters:

centralBody - An enumeration indicating the central body to create.

Returns:

The Point representing the central body.

getEarthNutationModel

@Nonnull
public final NutationModel getEarthNutationModel()

Creates a NutationModel which uses this JPL DE data for the nutation of the Earth.

Returns:

The Earth's nutation.

useForCentralBodyPositions

public final void useForCentralBodyPositions(@Nonnull
                                             CentralBodiesFacet centralBodiesFacet)

Uses this JPL DE data for the positions of the centers of mass of the central bodies in the specified CentralBodiesFacet instance. This also sets the positions of all the PlanetarySystemBarycenters.

In particular, the EarthMoonBarycenter is calculated using the EarthMoonMassRatio (get) and the updated positions of EarthCentralBody and MoonCentralBody. The other planetary system barycenters are set to exactly the same positions as their respective planets because technically the JPL DE data provides the barycenter positions rather than the physical positions of those planets.

The following example shows how to load a JPL DE file and use its data for the positions of the centers of mass of the central bodies in a CentralBodiesFacet:

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

// 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.getMoon();
moon.setFixedFrame(jplde.getMoonFixedFrame());

To use JPL DE data for a single central body, use JplDECenterOfMassPoint. This method also calls CentralBody.synchronizeOrigins() on the bodies.

Parameters:

centralBodiesFacet - The central bodies to update to use this JPL DE data.

Throws:

ArgumentNullException - Thrown when centralBodiesFacet is null.

createEarthMoonBarycenterPoint

@Nonnull
public final Point createEarthMoonBarycenterPoint()

Creates a Point that represents the position of the Earth-Moon barycenter calculated from the data in this class.

Returns:

The position of the Earth-Moon barycenter.

getFile

@Nonnull
public final JplDEFile getFile()

Gets the raw JPL DE file represented by this instance.