agi.foundation.coordinates

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

Class DelaunayElements

java.lang.Object

agi.foundation.coordinates.DelaunayElements

All Implemented Interfaces:

ICloneWithContext

public final class DelaunayElements
extends Object
implements ICloneWithContext

A set of Delaunay elements. This is a set of canonical angle-action variables that are commonly used in analytic orbit theory.

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

See Also:

KeplerianElements, ModifiedKeplerianElements, EquinoctialElements, KozaiIzsakMeanElements

Constructor Summary

Constructors

Constructor and Description
DelaunayElements(Cartesian position, Cartesian velocity, double gravitationalParameter) Initialize a set of Delaunay elements based upon a cartesian position and velocity.
DelaunayElements(Cartesian position, Cartesian velocity, double gravitationalParameter, double eccentricityTolerance, double inclinationTolerance) Initialize a set of Delaunay elements based upon a cartesian position and velocity.
DelaunayElements(double meanAnomaly, double argumentOfPeriapsis, double rightAscensionOfAscendingNode, double squareRootGravitySemimajorAxis, double angularMomentum, double angularMomentumAlongZ, double gravitationalParameter) Initialize a set of Delaunay elements.
DelaunayElements(EquinoctialElements elements) Initialize a set of Delaunay elements based on a set of EquinoctialElements.
DelaunayElements(KeplerianElements elements) Initialize a set of Delaunay elements based on a set of classical KeplerianElements.
DelaunayElements(ModifiedKeplerianElements elements) Initialize a set of Delaunay elements based on a set of ModifiedKeplerianElements.
DelaunayElements(Motion1<Cartesian> motion, double gravitationalParameter) Initializes a new instance from the specified cartesian motion and gravitational constant.
DelaunayElements(Motion1<Cartesian> motion, double gravitationalParameter, double eccentricityTolerance, double inclinationTolerance) 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	getAngularMomentum() Gets the angular momentum (distance squared per time).
double	getAngularMomentumAlongZ() Gets the Z Component of angular momentum (distance squared per time).
double	getArgumentOfPeriapsis() Gets the argument of periapsis (radians).
double	getGravitationalParameter() Gets the gravitational parameter used to compute these elements (distance cubed per time squared).
double	getMeanAnomaly() Gets the mean anomaly (radians).
double	getRightAscensionOfAscendingNode() Gets the right ascension of ascending node (radians).
double	getSquareRootGravitySemimajorAxis() Gets the square root of the product of gravitational parameter and semimajor axis, (distance squared per time).
Motion1<Cartesian>	toCartesian() Converts this set of Delaunay 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

DelaunayElements

public DelaunayElements(double meanAnomaly,
                        double argumentOfPeriapsis,
                        double rightAscensionOfAscendingNode,
                        double squareRootGravitySemimajorAxis,
                        double angularMomentum,
                        double angularMomentumAlongZ,
                        double gravitationalParameter)

Initialize a set of Delaunay elements.

Due to the numerical nature of these parameters, the element set will not precisely represent orbits with small eccentricities.

Parameters:

meanAnomaly - The mean anomaly (radians).

argumentOfPeriapsis - The argument of periapsis (radians).

rightAscensionOfAscendingNode - The right ascension of ascending node (radians).

squareRootGravitySemimajorAxis - The square root of the product of gravitational parameter and semimajor axis (distance squared per time).

angularMomentum - The angular momentum (distance squared per time).

angularMomentumAlongZ - The Z Component of angular momentum (distance squared per time).

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

Throws:

ArgumentOutOfRangeException - The following cases are invalid: angularMomentumAlongZ > angularMomentum, squareRootGravitySemimajorAxis < 0, or angularMomentum < 0.

DelaunayElements

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

Initialize a set of Delaunay elements based upon a cartesian position and velocity.

Parameters:

position - The position (distance).

velocity - The velocity (distance per time).

gravitationalParameter - The gravitational parameter used to create these elements (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).

IllegalStateException - Thrown when the elements provided cannot be represented by Delaunay elements.

DelaunayElements

public DelaunayElements(@Nonnull
                        Cartesian position,
                        @Nonnull
                        Cartesian velocity,
                        double gravitationalParameter,
                        double eccentricityTolerance,
                        double inclinationTolerance)

Initialize a set of Delaunay elements based upon a cartesian position and velocity.

Parameters:

position - The position (distance).

velocity - The velocity (distance per time).

gravitationalParameter - The gravitational parameter used to create these elements (distance cubed per time squared).

eccentricityTolerance - The tolerance which defines the value of 'zero' to use when checking whether the eccentricity is zero below which the orbit is circular.

inclinationTolerance - The tolerance which defines the value of 'zero' to use when checking whether the angular momentum vector is nearly vertical and the orbit is equatorial.

Throws:

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

IllegalStateException - Thrown when the elements provided cannot be represented by Delaunay elements.

DelaunayElements

public DelaunayElements(@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).

Throws:

IllegalStateException - Thrown when the elements provided cannot be represented by Delaunay elements.

DelaunayElements

public DelaunayElements(@Nonnull
                        Motion1<Cartesian> motion,
                        double gravitationalParameter,
                        double eccentricityTolerance,
                        double inclinationTolerance)

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).

eccentricityTolerance - The tolerance which defines the value of 'zero' to use when checking whether the eccentricity is zero below which the orbit is circular.

inclinationTolerance - The tolerance which defines the value of 'zero' to use when checking whether the inclination is zero below which the orbit is equatorial.

Throws:

IllegalStateException - Thrown when the elements provided cannot be represented by Delaunay elements.

DelaunayElements

public DelaunayElements(@Nonnull
                        ModifiedKeplerianElements elements)

Initialize a set of Delaunay elements based on a set of ModifiedKeplerianElements.

Parameters:

elements - A set of modified Keplerian elements.

Throws:

ArgumentNullException - Thrown if elements is null.

IllegalStateException - Thrown if the given elements do not represent a closed orbit.

DelaunayElements

public DelaunayElements(@Nonnull
                        KeplerianElements elements)

Initialize a set of Delaunay elements based on a set of classical KeplerianElements.

Parameters:

elements - A set of classical Keplerian elements.

Throws:

IllegalStateException - DelaunayElements throws an exception if the given elements do not represent a closed orbit.

DelaunayElements

public DelaunayElements(@Nonnull
                        EquinoctialElements elements)

Initialize a set of Delaunay elements based on a set of EquinoctialElements.

Parameters:

elements - A set of equinoctial 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 Delaunay elements to a cartesian position and velocity.

Returns:

Position and velocity (distance and distance per time).

getAngularMomentumAlongZ

public final double getAngularMomentumAlongZ()

Gets the Z Component of angular momentum (distance squared per time).

getAngularMomentum

public final double getAngularMomentum()

Gets the angular momentum (distance squared per time).

getSquareRootGravitySemimajorAxis

public final double getSquareRootGravitySemimajorAxis()

Gets the square root of the product of gravitational parameter and semimajor axis, (distance squared per time).

getRightAscensionOfAscendingNode

public final double getRightAscensionOfAscendingNode()

Gets the right ascension of ascending node (radians).

getArgumentOfPeriapsis

public final double getArgumentOfPeriapsis()

Gets the argument of periapsis (radians).

getMeanAnomaly

public final double getMeanAnomaly()

Gets the mean anomaly (radians).

getGravitationalParameter

public final double getGravitationalParameter()

Gets the gravitational parameter used to compute these elements (distance cubed per time squared).