KeplerianElements

java.lang.Object
- agi.foundation.coordinates.KeplerianElements

All Implemented Interfaces:

ICloneWithContext
```
public final class KeplerianElements
extends Object
implements ICloneWithContext
```
A set of classical Keplerian elements representing an elliptical orbit.

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

This class is meant to represent classical circular and elliptical orbits. For calculations involving parabolic or hyperbolic orbits, see ModifiedKeplerianElements.

See Also:

ModifiedKeplerianElements, EquinoctialElements, DelaunayElements, KozaiIzsakMeanElements

Constructor Summary

Constructors
Constructor and Description
`KeplerianElements(Cartesian position, Cartesian velocity, double gravitationalParameter)` Initialize a set of classical Keplerian elements from a `Cartesian` position and velocity.
`KeplerianElements(Cartesian position, Cartesian velocity, double gravitationalParameter, double eccentricityTolerance, double inclinationTolerance)` Initialize a set of classical Keplerian elements from a cartesian position and velocity.
`KeplerianElements(DelaunayElements elements)` Initialize a set of classical Keplerian elements from a set of `DelaunayElements`.
`KeplerianElements(DelaunayElements elements, double eccentricityTolerance, double inclinationTolerance)` Initialize a set of classical Keplerian elements from a set of `DelaunayElements`.
`KeplerianElements(double semimajorAxis, double eccentricity, double inclination, double argumentOfPeriapsis, double rightAscensionOfAscendingNode, double trueAnomaly, double gravitationalParameter)` Initialize a set of classical Keplerian orbital elements.
`KeplerianElements(EquinoctialElements elements)` Initialize a set of classical Keplerian elements from a set of `EquinoctialElements`.
`KeplerianElements(EquinoctialElements elements, double eccentricityTolerance, double inclinationTolerance)` Initialize a set of classical Keplerian elements from a set of `EquinoctialElements`.
`KeplerianElements(ModifiedKeplerianElements elements)` Initialize a set of classical Keplerian elements from a set of `ModifiedKeplerianElements`.
`KeplerianElements(Motion1<Cartesian> motion, double gravitationalParameter)` Initializes a new instance from the specified `Cartesian` motion and gravitational parameter.
`KeplerianElements(Motion1<Cartesian> motion, double gravitationalParameter, double eccentricityTolerance, double inclinationTolerance)` Initializes a new instance from the specified cartesian motion and gravitational constant.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Object`	`clone(CopyContext context)` Clones this object using the specified context.
`double`	`computeEccentricAnomaly()` Computes the eccentric anomaly based on the current Keplerian position.
`double`	`computeMeanAnomaly()` Computes the Mean anomaly based on the current Keplerian position.
`double`	`computeMeanMotion()` Computes the mean motion based on the current Keplerian elements.
`double`	`computePeriod()` Computes the orbital period of the current Keplerian elements.
`double`	`computeRadiusOfApoapsis()` Computes the apoapsis of the current Keplerian elements.
`double`	`computeRadiusOfPeriapsis()` Computes the periapsis of the current Keplerian elements.
`double`	`computeSemilatusRectum()` Computes the semilatus rectum of the current Keplerian elements.
`double`	`getArgumentOfPeriapsis()` Gets the argument of periapsis of the orbit, in radians.
`double`	`getEccentricity()` Gets the eccentricity of the orbit.
`double`	`getGravitationalParameter()` Gets the gravitational parameter used for this element set (distance cubed per time squared).
`double`	`getInclination()` Gets the inclination of the orbit, in radians.
`OrbitType`	`getOrbitType()` Gets the type of orbit represented by these elements.
`double`	`getRightAscensionOfAscendingNode()` Gets the right ascension of the ascending node of the orbit, in radians.
`double`	`getSemimajorAxis()` Gets the semimajor axis of the orbit (distance).
`double`	`getTrueAnomaly()` Gets the true anomaly of the orbit, in radians.
`Motion1<Cartesian>`	`toCartesian()` Returns a cartesian representation of these orbital elements.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         Cartesian position,
                         @Nonnull
                         Cartesian velocity,
                         double gravitationalParameter)
```
    Initialize a set of classical Keplerian elements from a Cartesian position and velocity. The given elements must represent a closed orbit. For other orbit types, use ModifiedKeplerianElements.
    
    Parameters:
    
    position - The cartesian position (distance).
    
    velocity - The cartesian velocity (distance per time).
    
    gravitationalParameter - The gravitational parameter to use to create this set (distance cubed per time squared).
    
    Throws:
    
    ArgumentOutOfRangeException - Thrown when the eccentricity is negative or not below unity or if the semimajor axis is not finitely positive.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         Motion1<Cartesian> motion,
                         double gravitationalParameter)
```
    Initializes a new instance from the specified Cartesian motion and gravitational parameter. The given elements must represent a closed orbit. For other orbit types, use ModifiedKeplerianElements.
    
    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:
    
    ArgumentOutOfRangeException - Thrown when the eccentricity is negative or not below unity or if the semimajor axis is not finitely positive.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         DelaunayElements elements)
```
    Initialize a set of classical Keplerian elements from a set of DelaunayElements.
    
    Parameters:
    
    elements - A set of Delaunay elements.
    
    Throws:
    
    ArgumentNullException - Thrown when elements is null.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         EquinoctialElements elements)
```
    Initialize a set of classical Keplerian elements from a set of EquinoctialElements.
    
    Parameters:
    
    elements - A set of Equinoctial elements.
    
    Throws:
    
    ArgumentNullException - Thrown when elements is null.
  - KeplerianElements
```
public KeplerianElements(double semimajorAxis,
                         double eccentricity,
                         double inclination,
                         double argumentOfPeriapsis,
                         double rightAscensionOfAscendingNode,
                         double trueAnomaly,
                         double gravitationalParameter)
```
    Initialize a set of classical Keplerian orbital elements. The given elements must represent a closed orbit. For other orbit types, use ModifiedKeplerianElements.
    The classification of the OrbitType (get) is exact so that if the user wants this instance of KeplerianElements to be classified as a Circular orbit, the eccentricity must be exactly zero. For parabolic or hyperbolic orbits, see ModifiedKeplerianElements.
    
    Parameters:
    
    semimajorAxis - Semimajor axis (distance).
    
    eccentricity - Eccentricity.
    
    inclination - Inclination (radians).
    
    argumentOfPeriapsis - Argument of periapsis (radians).
    
    rightAscensionOfAscendingNode - Right ascension of the ascending node (radians).
    
    trueAnomaly - True anomaly (radians).
    
    gravitationalParameter - Gravitational parameter (distance cubed per time squared).
    
    Throws:
    
    ArgumentOutOfRangeException - Thrown when eccentricity is negative, not below unity, or when semimajorAxis is not finitely positive, or when semimajorAxis is less than Constants.Epsilon8, or when inclination is less than zero or greater than π.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         Cartesian position,
                         @Nonnull
                         Cartesian velocity,
                         double gravitationalParameter,
                         double eccentricityTolerance,
                         double inclinationTolerance)
```
    Initialize a set of classical Keplerian elements from a cartesian position and velocity.
    
    Parameters:
    
    position - The cartesian position (distance).
    
    velocity - The cartesian velocity (distance per time).
    
    gravitationalParameter - The gravitational parameter to use to create this set (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 - The given elements must represent a closed orbit. The exception is thrown if the eccentricity is negative or not below unity or if the semimajor axis is not finitely positive. For other orbit types, use ModifiedKeplerianElements.
  - KeplerianElements
```
public KeplerianElements(@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:
    
    ArgumentException - The given elements must represent a closed orbit. The exception is thrown if the eccentricity is negative or not below unity or if the semimajor axis is not finitely positive. For other orbit types, use ModifiedKeplerianElements.
    
    ArgumentOutOfRangeException - Thrown if either eccentricityTolerance or inclinationTolerance is negative.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         ModifiedKeplerianElements elements)
```
    Initialize a set of classical Keplerian elements from a set of ModifiedKeplerianElements.
    
    Parameters:
    
    elements - The modified Keplerian elements.
    
    Throws:
    
    ArgumentNullException - Thrown when the parameter elements is null.
    
    IllegalStateException - The given elements must represent a closed orbit. The exception is thrown if the eccentricity is negative or not below unity or if the semimajor axis is not finitely positive. For other orbit types, use ModifiedKeplerianElements.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         DelaunayElements elements,
                         double eccentricityTolerance,
                         double inclinationTolerance)
```
    Initialize a set of classical Keplerian elements from a set of DelaunayElements.
    
    Parameters:
    
    elements - A set of Delaunay elements.
    
    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:
    
    ArgumentNullException - Thrown when the parameter elements is null.
    
    ArgumentOutOfRangeException - Thrown if either eccentricityTolerance or inclinationTolerance is negative.
  - KeplerianElements
```
public KeplerianElements(@Nonnull
                         EquinoctialElements elements,
                         double eccentricityTolerance,
                         double inclinationTolerance)
```
    Initialize a set of classical Keplerian elements from a set of EquinoctialElements.
    
    Parameters:
    
    elements - A set of Equinoctial elements.
    
    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:
    
    ArgumentNullException - Thrown when the parameter elements is null.
    
    ArgumentOutOfRangeException - Thrown if either eccentricityTolerance or inclinationTolerance is negative.
- 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()
```
    Returns a cartesian representation of these orbital elements.
    
    Returns:
    
    Cartesian elements that are equivalent to these KeplerianElements (distance and distance per time).
  - computeMeanAnomaly
```
public final double computeMeanAnomaly()
```
    Computes the Mean anomaly based on the current Keplerian position.
    
    Returns:
    
    The current mean anomaly (radians).
    
    Throws:
    
    IllegalStateException - Thrown if the OrbitType (get) does not represent either a circular or elliptical orbit. To find mean anomaly for parabolic or hyperbolic orbits, convert to ModifiedKeplerianElements.
    
    See Also:
    
    OrbitalElements.tryConvertTrueAnomalyToMeanAnomaly(double, double, double[])
  - computeEccentricAnomaly
```
public final double computeEccentricAnomaly()
```
    Computes the eccentric anomaly based on the current Keplerian position.
    Keplerian elements are not intended to represent parabolic and hyperbolic orbits. To find parabolic and hyperbolic anomalies, convert these elements to ModifiedKeplerianElements.
    
    Returns:
    
    The current eccentric anomaly (radians).
    
    Throws:
    
    IllegalStateException - Thrown when OrbitType (get) does not represent either a circular or elliptical orbit. To find mean anomaly for parabolic or hyperbolic orbits, convert to ModifiedKeplerianElements.
    
    See Also:
    
    OrbitalElements.tryConvertTrueAnomalyToEccentricAnomaly(double, double, double[])
  - computeMeanMotion
```
public final double computeMeanMotion()
```
    Computes the mean motion based on the current Keplerian elements.
    
    Returns:
    
    The mean motion (radians per time).
    
    Throws:
    
    IllegalStateException - Thrown if the OrbitType (get) does not represent either a circular or elliptical orbit. To find mean anomaly for parabolic or hyperbolic orbits, convert to ModifiedKeplerianElements.
  - computePeriod
```
public final double computePeriod()
```
    Computes the orbital period of the current Keplerian elements.
    
    Returns:
    
    The orbital period (time).
    
    Throws:
    
    IllegalStateException - If the OrbitType (get) does not represent a closed orbit (either circular or elliptical), there is no orbital period.
    
    See Also:
    
    OrbitalElements.tryComputePeriod(double, double, double[])
  - computeRadiusOfApoapsis
```
public final double computeRadiusOfApoapsis()
```
    Computes the apoapsis of the current Keplerian elements.
    
    Returns:
    
    The apoapsis (distance).
  - computeRadiusOfPeriapsis
```
public final double computeRadiusOfPeriapsis()
```
    Computes the periapsis of the current Keplerian elements.
    
    Returns:
    
    The periapsis (distance).
  - computeSemilatusRectum
```
public final double computeSemilatusRectum()
```
    Computes the semilatus rectum of the current Keplerian elements.
    
    Returns:
    
    The semilatus rectum (distance).
  - getSemimajorAxis
```
public final double getSemimajorAxis()
```
    Gets the semimajor axis of the orbit (distance).
    Semimajor axis represents half the distance between the periapsis and the apoapsis.
  - getEccentricity
```
public final double getEccentricity()
```
    Gets the eccentricity of the orbit.
    
    Eccentricity e can be calculated on the basis of semimajor axis a and semiminor axis b as follows:
```
    e = sqrt(1 - (b / a)^2)
    
```
    Referring to the following diagram, e can also be expressed as a / f, where f is the distance from the center of the ellipse to the center of mass of the central body:
  - getInclination
```
public final double getInclination()
```
    Gets the inclination of the orbit, in radians.
    
    The inclination of the orbit is its tilt with reference to the Equatorial plane, or, in the diagram below, the angle i between the central body's spin (Z) axis and the orbit's angular momentum vector.
    
    In the above diagram, ω is the argument of periapsis, θ is the true anomaly, and Ω is the right ascension of the ascending node (RAAN).
  - getArgumentOfPeriapsis
```
public final double getArgumentOfPeriapsis()
```
    Gets the argument of periapsis of the orbit, in radians.
    
    The argument of periapsis, ω, is the angular distance between the ascending node and periapsis:
    
    In the above diagram, Ω is the right ascension of the ascending node (RAAN), θ is the true anomaly, and i is the inclination.
  - getRightAscensionOfAscendingNode
```
public final double getRightAscensionOfAscendingNode()
```
    Gets the right ascension of the ascending node of the orbit, in radians.
    
    The ascending node is the point where the satellite crosses the equator moving south to north. In the diagram below, this point is referenced from the +X direction, which points in the Vernal Equinox direction. The angle between the X axis and the ascending node is called the right ascension of the ascending node (RAAN), represented here by Ω.
    
    In the above diagram, ω is the argument of periapsis, θ is the true anomaly, and i is the inclination.
  - getTrueAnomaly
```
public final double getTrueAnomaly()
```
    Gets the true anomaly of the orbit, in radians.
    
    True anomaly is used to represent the satellite's instantaneous position with respect to periapsis, shown here as the angle θ:
    
    In the above diagram, ω is the argument of periapsis, i is the inclination, and Ω is the right ascension of the ascending node (RAAN).
  - getGravitationalParameter
```
public final double getGravitationalParameter()
```
    Gets the gravitational parameter used for this element set (distance cubed per time squared).
  - getOrbitType
```
@Nonnull
public final OrbitType getOrbitType()
```
    Gets the type of orbit represented by these elements.

Class KeplerianElements

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

KeplerianElements

KeplerianElements

KeplerianElements

KeplerianElements

KeplerianElements

KeplerianElements

KeplerianElements

KeplerianElements

KeplerianElements

Method Detail

clone

toCartesian

computeMeanAnomaly

computeEccentricAnomaly

computeMeanMotion

computePeriod

computeRadiusOfApoapsis

computeRadiusOfPeriapsis

computeSemilatusRectum

getSemimajorAxis

getEccentricity

getInclination

getArgumentOfPeriapsis

getRightAscensionOfAscendingNode

getTrueAnomaly

getGravitationalParameter

getOrbitType