ModifiedKeplerianElements

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

All Implemented Interfaces:

ICloneWithContext, IEquatableDefinition
```
public final class ModifiedKeplerianElements
extends Object
implements ICloneWithContext, IEquatableDefinition
```
Modified Keplerian orbital elements. These are the same as the Classical/Keplerian orbital elements except that Radius of Periapsis and the inverse of Semimajor Axis are used instead of Semimajor Axis and Eccentricity. This is useful because the Radius of Periapsis is well defined for all but rectilinear orbits. For Eccentricity, use ModifiedKeplerianElements.computeEccentricity().

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

See Also:

KeplerianElements, EquinoctialElements, DelaunayElements, KozaiIzsakMeanElements

Constructor Summary

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

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`	`computeEccentricity()` Computes the eccentricity based on the current elements.
`double`	`computeHyperbolicAnomaly()` Computes the hyperbolic 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`	`computeParabolicAnomaly()` Computes the parabolic anomaly based on the current Keplerian position.
`double`	`computePeriod()` Computes the orbital period of the current Keplerian elements.
`double`	`computeRadiusOfApoapsis()` Computes the radius of apoapsis based on the current elements.
`double`	`getArgumentOfPeriapsis()` Gets the argument of periapsis of the orbit, in radians.
`int`	`getDefinitionHashCode()` Gets a hash code representing the definition of this object.
`double`	`getGravitationalParameter()` Gets the gravitational parameter associated with this element set (distance cubed per time squared).
`double`	`getInclination()` Gets the inclination of the orbit, in radians.
`double`	`getInverseSemimajorAxis()` Gets the inverse of the semimajor axis.
`OrbitType`	`getOrbitType()` Gets the type of orbit represented by these elements.
`double`	`getRadiusOfPeriapsis()` Gets the radius of periapsis of the orbit (distance).
`double`	`getRightAscensionOfAscendingNode()` Gets the right ascension of the ascending node of the orbit, in radians.
`double`	`getTrueAnomaly()` Gets the true anomaly of the orbit, in radians.
`boolean`	`isSameDefinition(Object other)` Determines if this object has the same definition as another object.
`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
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 Cartesian position,
                                 @Nonnull
                                 Cartesian velocity,
                                 double gravitationalParameter)
```
    Initializes a new instance from the specified Cartesian position, Cartesian velocity, and gravitational parameter.
    If the orbit eccentricity turns out to be less than Constants.Epsilon12, the argument of periapsis will be aligned with the ascending node (the value is set to zero).
    
    Parameters:
    
    position - The cartesian position (distance).
    
    velocity - The cartesian velocity (distance per time).
    
    gravitationalParameter - The gravitational parameter for the central body (distance cubed per time squared).
    
    Throws:
    
    ArgumentOutOfRangeException - Thrown when the magnitude of position is nearly zero (less than Constants.Epsilon8).
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 Motion1<Cartesian> motion,
                                 double gravitationalParameter)
```
    Initializes a new instance from the specified Cartesian motion and gravitational constant.
    If the orbit eccentricity turns out to be less than Constants.Epsilon12, the argument of periapsis will be aligned with the ascending node (the value is set to zero).
    
    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 magnitude of the position is nearly zero (less than Constants.Epsilon8).
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 KeplerianElements elements)
```
    Initialize a new instance from the given set of classical KeplerianElements.
    
    Parameters:
    
    elements - A set of classical Keplerian elements.
    
    Throws:
    
    ArgumentNullException - Thrown when elements is null.
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 DelaunayElements elements)
```
    Initializes a new instance for the specified DelaunayElements.
    
    Parameters:
    
    elements - The set of Delaunay elements.
    
    Throws:
    
    ArgumentNullException - Thrown when elements is null.
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 EquinoctialElements elements)
```
    Initialize a new instance from the given set of EquinoctialElements.
    
    Parameters:
    
    elements - The set of Equinoctial elements.
    
    Throws:
    
    ArgumentNullException - Thrown when elements is null.
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(double radiusOfPeriapsis,
                                 double inverseSemimajorAxis,
                                 double inclination,
                                 double argumentOfPeriapsis,
                                 double rightAscensionOfAscendingNode,
                                 double trueAnomaly,
                                 double gravitationalParameter)
```
    Initialize a set of modified Keplerian elements.
    The classification of the OrbitType (get) is exact, so to be classified as a OrbitType.CIRCULAR orbit, the inverse of radiusOfPeriapsis must be exactly equal to inverseSemimajorAxis.
    
    Parameters:
    
    radiusOfPeriapsis - Radius of periapsis (distance).
    
    inverseSemimajorAxis - The inverse of semimajor axis (distance).
    
    inclination - Inclination, in radians.
    
    argumentOfPeriapsis - Argument of periapsis, in radians.
    
    rightAscensionOfAscendingNode - Right ascension of the ascending node, in radians.
    
    trueAnomaly - True anomaly, in radians.
    
    gravitationalParameter - The gravitational parameter associated with these elements (distance cubed per time squared).
    
    Throws:
    
    ArgumentOutOfRangeException - Thrown when inclination is less than zero or greater than π.
    
    ArgumentOutOfRangeException - Thrown when the orbit is hyperbolic and the absolute value of trueAnomaly is greater than or equal to arccosine(1 / eccentricity).
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 Cartesian position,
                                 @Nonnull
                                 Cartesian velocity,
                                 double gravitationalParameter,
                                 double eccentricityTolerance,
                                 double inclinationTolerance)
```
    Initializes a new instance from the specified Cartesian motion and gravitational constant.
    If the orbit eccentricity turns out to be less than Constants.Epsilon12, the argument of periapsis will be aligned with the ascending node (the value is set to zero).
    
    Parameters:
    
    position - The cartesian position (distance).
    
    velocity - The cartesian velocity (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:
    
    ArgumentOutOfRangeException - Thrown when the magnitude of position is nearly zero (less than Constants.Epsilon8), or when either eccentricityTolerance or inclinationTolerance is negative.
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 Motion1<Cartesian> motion,
                                 double gravitationalParameter,
                                 double eccentricityTolerance,
                                 double inclinationTolerance)
```
    Initializes a new instance from the specified Cartesian motion and gravitational parameter.
    
    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:
    
    ArgumentOutOfRangeException - Thrown when either eccentricityTolerance or inclinationTolerance is negative.
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 DelaunayElements elements,
                                 double eccentricityTolerance,
                                 double inclinationTolerance)
```
    Initializes a new instance for the specified DelaunayElements.
    
    Parameters:
    
    elements - The 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 elements is null.
    
    ArgumentOutOfRangeException - Thrown when either eccentricityTolerance or inclinationTolerance is negative.
  - ModifiedKeplerianElements
```
public ModifiedKeplerianElements(@Nonnull
                                 EquinoctialElements elements,
                                 double eccentricityTolerance,
                                 double inclinationTolerance)
```
    Initialize a new instance from the given set of EquinoctialElements.
    
    Parameters:
    
    elements - The 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 elements is null.
    
    ArgumentOutOfRangeException - Thrown when 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.
  - isSameDefinition
```
public final boolean isSameDefinition(Object other)
```
    Determines if this object has the same definition as another object.
    This method is very similar to Object.equals(Object) except that it explicitly considers the "definitions" of the two objects for objects that do not typically act like values. The definition of an object typically includes all of the fields of the object.
    
    Specified by:
    
    isSameDefinition in interface IEquatableDefinition
    
    Parameters:
    
    other - The other instance to compare to this one.
    
    Returns:
    
    true if this object has the same definition as the specified one. false if the other object is null, a different type than this one, or if this object and the specified one have different definitions.
  - getDefinitionHashCode
```
public final int getDefinitionHashCode()
```
    Gets a hash code representing the definition of this object.
    This method is very similar to Object.hashCode() except that it explicitly includes the "definition" of the object even if the object does not typically act like a value. The definition of an object typically includes all of the fields of the object. The value returned by this method should NOT change. This means that two objects for which ModifiedKeplerianElements.isSameDefinition(java.lang.Object) returns true will not necessarily have the same hash code if one or the other was changed after the hash code was first obtained.
    
    Specified by:
    
    getDefinitionHashCode in interface IEquatableDefinition
    
    Returns:
    
    The hash code.
  - getInverseSemimajorAxis
```
public final double getInverseSemimajorAxis()
```
    Gets the inverse of the semimajor axis.
  - getRadiusOfPeriapsis
```
public final double getRadiusOfPeriapsis()
```
    Gets the radius of periapsis of the orbit (distance).
  - 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 associated with this element set (distance cubed per time squared).
  - getOrbitType
```
@Nonnull
public final OrbitType getOrbitType()
```
    Gets the type of orbit represented by these elements.
  - computeEccentricity
```
public final double computeEccentricity()
```
    Computes the eccentricity based on the current elements.
    
    Returns:
    
    The eccentricity based on the current elements.
  - computeRadiusOfApoapsis
```
public final double computeRadiusOfApoapsis()
```
    Computes the radius of apoapsis based on the current elements.
    
    Returns:
    
    The radius of apoapsis based on the current elements.
  - computeMeanAnomaly
```
public final double computeMeanAnomaly()
```
    Computes the mean anomaly based on the current Keplerian position.
    
    Returns:
    
    The current mean anomaly, in radians.
    
    Throws:
    
    IllegalStateException - In the case of a hyperbolic orbit, the true anomaly 'v' is bound within: -π + Acos(1/e) < v < π - Acos(1/e). Otherwise, the method throws an exception.
    
    See Also:
    
    OrbitalElements.tryConvertTrueAnomalyToMeanAnomaly(double, double, double[])
  - computeMeanMotion
```
public final double computeMeanMotion()
```
    Computes the mean motion based on the current Keplerian elements.
    
    Returns:
    
    The mean angular motion (radians per time).
  - computeEccentricAnomaly
```
public final double computeEccentricAnomaly()
```
    Computes the eccentric anomaly based on the current Keplerian position.
    
    Returns:
    
    The current eccentric anomaly, in radians.
    
    Throws:
    
    IllegalStateException - Thrown when the OrbitType (get) is not circular or elliptical.
    
    See Also:
    
    OrbitalElements.tryConvertTrueAnomalyToEccentricAnomaly(double, double, double[])
  - computeParabolicAnomaly
```
public final double computeParabolicAnomaly()
```
    Computes the parabolic anomaly based on the current Keplerian position.
    The parabolic anomaly is an angular measure defined to be zero at periapsis, unity at the latus rectum point, and goes to infinity as true anomaly approaches π.
    
    Returns:
    
    The current parabolic anomaly, in radians.
    
    Throws:
    
    IllegalStateException - Thrown if the orbit type is not parabolic.
  - computeHyperbolicAnomaly
```
public final double computeHyperbolicAnomaly()
```
    Computes the hyperbolic anomaly based on the current Keplerian position.
    The hyperbolic anomaly is analogous to the eccentric anomaly but uses an equilateral hyperbola instead of a circle.
    
    Returns:
    
    The current hyperbolic anomaly, in radians.
    
    Throws:
    
    IllegalStateException - Thrown if the orbit type is not hyperbolic.
  - computePeriod
```
public final double computePeriod()
```
    Computes the orbital period of the current Keplerian elements. For parabolic and hyperbolic orbits the method returns Double.POSITIVE_INFINITY.
    
    Returns:
    
    The orbital period (time).
    
    Throws:
    
    IllegalStateException - Thrown if GravitationalParameter (get) is negative or zero.
    
    See Also:
    
    OrbitalElements.tryComputePeriod(double, double, double[])
  - toCartesian
```
@Nonnull
public final Motion1<Cartesian> toCartesian()
```
    Returns a cartesian representation of these orbital elements.
    
    Returns:
    
    Cartesian elements that are equivalent to these ModifiedKeplerianElements.
    
    Throws:
    
    IllegalStateException - Throws an exception in the case where the values become singular, namely when the true anomaly is π in the case of a parabolic orbit.

Class ModifiedKeplerianElements

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

ModifiedKeplerianElements

Method Detail

clone

isSameDefinition

getDefinitionHashCode

getInverseSemimajorAxis

getRadiusOfPeriapsis

getInclination

getArgumentOfPeriapsis

getRightAscensionOfAscendingNode

getTrueAnomaly

getGravitationalParameter

getOrbitType

computeEccentricity

computeRadiusOfApoapsis

computeMeanAnomaly

computeMeanMotion

computeEccentricAnomaly

computeParabolicAnomaly

computeHyperbolicAnomaly

computePeriod

toCartesian