agi.foundation.coordinates

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

Class EquinoctialElements

java.lang.Object

agi.foundation.coordinates.EquinoctialElements

All Implemented Interfaces:

ICloneWithContext

public final class EquinoctialElements
extends Object
implements ICloneWithContext

A set of equinoctial orbital elements. This is a nonsingular orbital element set that is often used in operational systems since it is well behaved for small eccentricities and inclinations. The Direction (get) element of the structure indicates whether the orbit is posigrade or retrograde.

All units are SI unless indicated otherwise. For more information see the Units topic.

See Also:

KeplerianElements, ModifiedKeplerianElements, DelaunayElements, KozaiIzsakMeanElements

Constructor Summary

Constructors

Constructor and Description
EquinoctialElements(Cartesian position, Cartesian velocity, double gravitationalParameter) Initialize a set of equinoctial elements from cartesian position and velocity.
EquinoctialElements(DelaunayElements elements) Initialize a set of equinoctial elements from a set of DelaunayElements.
EquinoctialElements(double semimajorAxis, double eccentricitySineLongitudeOfPeriapsis, double eccentricityCosineLongitudeOfPeriapsis, double inclinationAndRightAscensionSineParameter, double inclinationAndRightAscensionCosineParameter, double meanLongitude, boolean isPosigrade, double gravitationalParameter) Initialize a set of equinoctial elements.
EquinoctialElements(KeplerianElements elements) Initialize a set of equinoctial elements from a set of classical KeplerianElements.
EquinoctialElements(ModifiedKeplerianElements elements) Initialize a set of equinoctial elements from a set of ModifiedKeplerianElements.
EquinoctialElements(Motion1<Cartesian> motion, double gravitationalParameter) Initializes a new instance from the specified cartesian motion and gravitational constant.

Method Summary

Modifier and Type	Method and Description
Object	clone(CopyContext context) Clones this object using the specified context.
double	getDirection() Gets the parameter indicating whether this orbit is posigrade (+1.0) or retrograde (-1.0).
double	getEccentricityCosineLongitudeOfPeriapsis() Gets the Eccentricity * Cos(Argument Of Periapsis + Direction (get)*Right Ascension Of Ascending Node)
double	getEccentricitySineLongitudeOfPeriapsis() Gets the Eccentricity * Sin(Argument Of Periapsis + Direction (get)*Right Ascension Of Ascending Node)
double	getGravitationalParameter() Gets the gravitational parameter associated with this element set (distance cubed per time squared).
double	getInclinationAndRightAscensionCosineParameter() Gets the Sin(Inclination)*Cos(Right Ascension Of Ascending Node) / (1 + Cos(Inclination) )
double	getInclinationAndRightAscensionSineParameter() Gets the Sin(Inclination)*Sin(Right Ascension Of Ascending Node) / (1 + Cos(Inclination) )
double	getMeanLongitude() Gets the Mean Anomaly + Argument Of Periapsis + Direction (get)*Right Ascension Of Ascending Node (radians)
double	getSemimajorAxis() Gets the Semimajor axis (distance).
static double	meanLongitudeToEccentricLongitude(double meanLongitude, double eccentricitySineLongitudeOfPeriapsis, double eccentricityCosineLongitudeOfPeriapsis) Converts the longitude of mean anomaly to longitude of eccentric anomaly.
Motion1<Cartesian>	toCartesian() Converts this set of equinoctial elements to a cartesian position and velocity.

Methods inherited from class java.lang.Object

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

Constructor Detail

EquinoctialElements

public EquinoctialElements(double semimajorAxis,
                           double eccentricitySineLongitudeOfPeriapsis,
                           double eccentricityCosineLongitudeOfPeriapsis,
                           double inclinationAndRightAscensionSineParameter,
                           double inclinationAndRightAscensionCosineParameter,
                           double meanLongitude,
                           boolean isPosigrade,
                           double gravitationalParameter)

Initialize a set of equinoctial elements.

Parameters:

semimajorAxis - The semimajor axis (distance).

eccentricitySineLongitudeOfPeriapsis - Eccentricity * Sin(Argument Of Periapsis + Direction (get) * Right Ascension Of Ascending Node)

eccentricityCosineLongitudeOfPeriapsis - Eccentricity * Cos(Argument Of Periapsis + Direction (get) * Right Ascension Of Ascending Node)

inclinationAndRightAscensionSineParameter - Sin(Inclination) * Sin(Right Ascension Of Ascending Node) / (1 + Cos(Inclination) )

inclinationAndRightAscensionCosineParameter - Sin(Inclination) * Cos(Right Ascension Of Ascending Node) / (1 + Cos(Inclination) )

meanLongitude - Mean Anomaly + Argument Of Periapsis + Direction (get) * Right Ascension Of Ascending Node (radians)

isPosigrade - Boolean indicating whether this orbit is posigrade (true) or retrograde (false).

gravitationalParameter - Gravitational parameter associated with these elements (distance cubed per time squared).

Throws:

IllegalStateException - Thrown if the orbit represented by these elements does not constitute a closed orbit (eccentricity must be between zero and unity).

EquinoctialElements

public EquinoctialElements(@Nonnull
                           Cartesian position,
                           @Nonnull
                           Cartesian velocity,
                           double gravitationalParameter)

Initialize a set of equinoctial elements from cartesian position and velocity.

Parameters:

position - Cartesian position (distance).

velocity - Cartesian velocity (distance per time).

gravitationalParameter - Gravitational parameter (distance cubed per time squared).

Throws:

IllegalStateException - Thrown when the position and velocity represent an open orbit (with an eccentricity greater than or equal to one).

EquinoctialElements

public EquinoctialElements(@Nonnull
                           Motion1<Cartesian> motion,
                           double gravitationalParameter)

Initializes a new instance from the specified cartesian motion and gravitational constant.

Parameters:

motion - The cartesian position and velocity (distance and distance per time).

gravitationalParameter - The gravitational parameter for the central body (distance cubed per time squared).

EquinoctialElements

public EquinoctialElements(@Nonnull
                           ModifiedKeplerianElements elements)

Initialize a set of equinoctial elements from a set of ModifiedKeplerianElements.

Parameters:

elements - A set of modified Keplerian elements.

Throws:

ArgumentNullException - Thrown if elements is null.

IllegalStateException - Thrown when the provided equinoctial elements represent an open orbit.

EquinoctialElements

public EquinoctialElements(@Nonnull
                           KeplerianElements elements)

Initialize a set of equinoctial elements from a set of classical KeplerianElements.

Parameters:

elements - A set of classical Keplerian elements.

Throws:

ArgumentException - EquinoctialElements cannot represent open orbits.

EquinoctialElements

public EquinoctialElements(@Nonnull
                           DelaunayElements elements)

Initialize a set of equinoctial elements from a set of DelaunayElements.

Parameters:

elements - A set of Delaunay elements.

Method Detail

clone

public final Object clone(CopyContext context)

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

@Override
public void updateEvaluatorReferences(CopyContext context) {
    evaluatorReference = context.updateReference(evaluatorReference);
}

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

toCartesian

@Nonnull
public final Motion1<Cartesian> toCartesian()

Converts this set of equinoctial elements to a cartesian position and velocity.

Returns:

The corresponding cartesian motion containing position and velocity (distance and distance per time).

meanLongitudeToEccentricLongitude

public static double meanLongitudeToEccentricLongitude(double meanLongitude,
                                                       double eccentricitySineLongitudeOfPeriapsis,
                                                       double eccentricityCosineLongitudeOfPeriapsis)

Converts the longitude of mean anomaly to longitude of eccentric anomaly.

Parameters:

meanLongitude - The longitude of the mean anomaly (radians).

eccentricitySineLongitudeOfPeriapsis - The sine term of the equinoctial elements.

eccentricityCosineLongitudeOfPeriapsis - The cosine term of the equinoctial elements.

Returns:

The longitude of the eccentric anomaly (radians).

Throws:

IllegalStateException - This method throws an exception if the orbit is not closed.

IllegalStateException - Thrown when the provided arguments do not allow this function to converge.

See Also:

EquinoctialElements.getEccentricitySineLongitudeOfPeriapsis(), EquinoctialElements.getEccentricityCosineLongitudeOfPeriapsis()

getSemimajorAxis

public final double getSemimajorAxis()

Gets the Semimajor axis (distance).

getEccentricitySineLongitudeOfPeriapsis

public final double getEccentricitySineLongitudeOfPeriapsis()

Gets the Eccentricity * Sin(Argument Of Periapsis + Direction (get)*Right Ascension Of Ascending Node)

getEccentricityCosineLongitudeOfPeriapsis

public final double getEccentricityCosineLongitudeOfPeriapsis()

Gets the Eccentricity * Cos(Argument Of Periapsis + Direction (get)*Right Ascension Of Ascending Node)

getInclinationAndRightAscensionSineParameter

public final double getInclinationAndRightAscensionSineParameter()

Gets the Sin(Inclination)*Sin(Right Ascension Of Ascending Node) / (1 + Cos(Inclination) )

getInclinationAndRightAscensionCosineParameter

public final double getInclinationAndRightAscensionCosineParameter()

Gets the Sin(Inclination)*Cos(Right Ascension Of Ascending Node) / (1 + Cos(Inclination) )

getMeanLongitude

public final double getMeanLongitude()

Gets the Mean Anomaly + Argument Of Periapsis + Direction (get)*Right Ascension Of Ascending Node (radians)

getDirection

public final double getDirection()

Gets the parameter indicating whether this orbit is posigrade (+1.0) or retrograde (-1.0).

getGravitationalParameter

public final double getGravitationalParameter()

Gets the gravitational parameter associated with this element set (distance cubed per time squared).