LifetimeOrbitPropagator

java.lang.Object
- agi.foundation.infrastructure.DefinitionalObject
- - agi.foundation.propagators.LifetimeOrbitPropagator

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable
```
public final class LifetimeOrbitPropagator
extends DefinitionalObject
```
Propagates a set of initial conditions using a long-term propagation technique to determine when the orbit is expected to decay, based on the evolution of the mean orbital elements under the effects of gravitational, atmospheric, and solar perturbations.

Constructor Summary

Constructors
Constructor and Description

LifetimeOrbitPropagator()
Initializes a new instance.

Constructors
Constructor and Description
`LifetimeOrbitPropagator()` Initializes a new instance.

Method Summary

All Methods Instance Methods Concrete Methods
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.
`Object`	`clone(CopyContext context)` Clones this object using the specified context.
`protected int`	`computeCurrentDefinitionHashCode()` Computes a hash code based on the current properties of this object.
`OrbitLifetimeResults`	`computeLifetime()` Compute the set of metrics describing the time history of the orbit as well as the number of orbit revolutions and the time at which the orbit is expected to decay.
`OrbitLifetimeResults`	`computeLifetime(ITrackCalculationProgress progress)` Compute the set of metrics describing the time history of the orbit as well as the number of orbit revolutions and the time at which the orbit is expected to decay.
`void`	`enumerateDependencies(DependencyEnumerator enumerator)` Enumerates the dependencies of this object by calling `DependencyEnumerator#enumerate(T)` for each object that this object directly depends upon.
`ScalarAtmosphericDensity`	`getAtmosphericDensity()` Gets the model for atmospheric density.
`CentralBody`	`getCentralBody()` Gets the instance to use to define the principal frame and shape of the central body.
`double`	`getDecayAltitude()` Gets the altitude to use to determine when a satellite will permanently decay.
`double`	`getDragCoefficient()` Gets the coefficient of drag associated with the aerodynamic profile of the satellite.
`double`	`getDragCrossSectionalArea()` Gets the mean area of the satellite which is presented perpendicular to the relative velocity of the atmosphere and produces drag.
`Duration`	`getDurationLimit()` Gets the maximum total time to spend propagating, based on the `OrbitLimitType` (`get` / `set`).
`KozaiIzsakMeanElements`	`getInitialConditions()` Gets the mean elements representing the initial conditions of the orbit.
`JulianDate`	`getInitialEpoch()` Gets the time at which the `InitialConditions` (`get` / `set`) are valid.
`int`	`getNumberOfGaussianQuadratures()` Gets the number of Gaussian quadratures to use when integrating.
`int`	`getOrbitCountLimit()` Gets the number of orbits past which to stop propagation.
`LifetimeCalculationLimitType`	`getOrbitLimitType()` Gets the limitation for when the lifetime propagator calculation should stop its iteration.
`int`	`getOrbitsPerCalculation()` Gets the number of complete orbits to propagate as part of a single iteration of the integration of the orbital parameters over time.
`double`	`getReflectiveCrossSectionalArea()` Gets the mean area presented to the illuminating body (the Sun) during propagation, in square meters.
`double`	`getReflectivityCoefficient()` Gets the coefficient of reflectivity for the satellite.
`double`	`getSatelliteMass()` Gets the mass of the satellite, in kilograms.
`boolean`	`getUseRotatingAtmosphere()` Gets a value indicating whether to model the atmosphere as rotating rather than static.
`boolean`	`getUseSecondOrderOblatenessCorrection()` Gets a value indicating whether to use second order oblateness (J2) correction when propagating the mean orbital elements.
`void`	`setAtmosphericDensity(ScalarAtmosphericDensity value)` Sets the model for atmospheric density.
`void`	`setCentralBody(CentralBody value)` Sets the instance to use to define the principal frame and shape of the central body.
`void`	`setDecayAltitude(double value)` Sets the altitude to use to determine when a satellite will permanently decay.
`void`	`setDragCoefficient(double value)` Sets the coefficient of drag associated with the aerodynamic profile of the satellite.
`void`	`setDragCrossSectionalArea(double value)` Sets the mean area of the satellite which is presented perpendicular to the relative velocity of the atmosphere and produces drag.
`void`	`setDurationLimit(Duration value)` Sets the maximum total time to spend propagating, based on the `OrbitLimitType` (`get` / `set`).
`void`	`setInitialConditions(KozaiIzsakMeanElements value)` Sets the mean elements representing the initial conditions of the orbit.
`void`	`setInitialEpoch(JulianDate value)` Sets the time at which the `InitialConditions` (`get` / `set`) are valid.
`void`	`setNumberOfGaussianQuadratures(int value)` Sets the number of Gaussian quadratures to use when integrating.
`void`	`setOrbitCountLimit(int value)` Sets the number of orbits past which to stop propagation.
`void`	`setOrbitLimitType(LifetimeCalculationLimitType value)` Sets the limitation for when the lifetime propagator calculation should stop its iteration.
`void`	`setOrbitsPerCalculation(int value)` Sets the number of complete orbits to propagate as part of a single iteration of the integration of the orbital parameters over time.
`void`	`setReflectiveCrossSectionalArea(double value)` Sets the mean area presented to the illuminating body (the Sun) during propagation, in square meters.
`void`	`setReflectivityCoefficient(double value)` Sets the coefficient of reflectivity for the satellite.
`void`	`setSatelliteMass(double value)` Sets the mass of the satellite, in kilograms.
`void`	`setUseRotatingAtmosphere(boolean value)` Sets a value indicating whether to model the atmosphere as rotating rather than static.
`void`	`setUseSecondOrderOblatenessCorrection(boolean value)` Sets a value indicating whether to use second order oblateness (J2) correction when propagating the mean orbital elements.

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

- Constructor Detail
  - LifetimeOrbitPropagator
```
public LifetimeOrbitPropagator()
```
    Initializes a new instance.
- Method Detail
  - clone
```
public 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
    
    Specified by:
    
    clone in class DefinitionalObject
    
    Parameters:
    
    context - The context to use to perform the copy.
    
    Returns:
    
    A new instance which is a copy of this object.
  - checkForSameDefinition
```
protected 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.
  - 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 LifetimeOrbitPropagator.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.
  - getCentralBody
```
public final CentralBody getCentralBody()
```
    Gets the instance to use to define the principal frame and shape of the central body. By default, this is the EarthCentralBody from the CentralBodiesFacet.
  - setCentralBody
```
public final void setCentralBody(CentralBody value)
```
    Sets the instance to use to define the principal frame and shape of the central body. By default, this is the EarthCentralBody from the CentralBodiesFacet.
  - getAtmosphericDensity
```
public final ScalarAtmosphericDensity getAtmosphericDensity()
```
    Gets the model for atmospheric density. This includes the data to use for geomagnetic flux and solar radiation. However, this instance will be copied and the TargetPoint (get / set) will be replaced during propagation with the position determined by this propagator.
  - setAtmosphericDensity
```
public final void setAtmosphericDensity(ScalarAtmosphericDensity value)
```
    Sets the model for atmospheric density. This includes the data to use for geomagnetic flux and solar radiation. However, this instance will be copied and the TargetPoint (get / set) will be replaced during propagation with the position determined by this propagator.
  - getOrbitLimitType
```
@Nonnull
public final LifetimeCalculationLimitType getOrbitLimitType()
```
    Gets the limitation for when the lifetime propagator calculation should stop its iteration.
  - setOrbitLimitType
```
public final void setOrbitLimitType(@Nonnull
                                    LifetimeCalculationLimitType value)
```
    Sets the limitation for when the lifetime propagator calculation should stop its iteration.
  - getInitialConditions
```
public final KozaiIzsakMeanElements getInitialConditions()
```
    Gets the mean elements representing the initial conditions of the orbit. These elements commonly represent the position in the TrueEquatorTrueEquinoxFrame (get / set) frame.
  - setInitialConditions
```
public final void setInitialConditions(KozaiIzsakMeanElements value)
```
    Sets the mean elements representing the initial conditions of the orbit. These elements commonly represent the position in the TrueEquatorTrueEquinoxFrame (get / set) frame.
  - getOrbitCountLimit
```
public final int getOrbitCountLimit()
```
    Gets the number of orbits past which to stop propagation. This limits the runtime of the propagator, based on the OrbitLimitType (get / set). By default, this is set to 100,000 orbits.
  - setOrbitCountLimit
```
public final void setOrbitCountLimit(int value)
```
    Sets the number of orbits past which to stop propagation. This limits the runtime of the propagator, based on the OrbitLimitType (get / set). By default, this is set to 100,000 orbits.
  - getDurationLimit
```
@Nonnull
public final Duration getDurationLimit()
```
    Gets the maximum total time to spend propagating, based on the OrbitLimitType (get / set). By default, this is set to 10 years.
  - setDurationLimit
```
public final void setDurationLimit(@Nonnull
                                   Duration value)
```
    Sets the maximum total time to spend propagating, based on the OrbitLimitType (get / set). By default, this is set to 10 years.
  - getOrbitsPerCalculation
```
public final int getOrbitsPerCalculation()
```
    Gets the number of complete orbits to propagate as part of a single iteration of the integration of the orbital parameters over time. This parameter allows you to control the performance of the propagator directly. The fewer orbits per calculation, the more precise the estimate will be, but at the expense of computation time. The higher number of orbits per calculation, the less precise the estimate will be, but calculations complete much faster. By default, this is set to 1 orbit, but 10 can be used for a faster approximation.
  - setOrbitsPerCalculation
```
public final void setOrbitsPerCalculation(int value)
```
    Sets the number of complete orbits to propagate as part of a single iteration of the integration of the orbital parameters over time. This parameter allows you to control the performance of the propagator directly. The fewer orbits per calculation, the more precise the estimate will be, but at the expense of computation time. The higher number of orbits per calculation, the less precise the estimate will be, but calculations complete much faster. By default, this is set to 1 orbit, but 10 can be used for a faster approximation.
  - getNumberOfGaussianQuadratures
```
public final int getNumberOfGaussianQuadratures()
```
    Gets the number of Gaussian quadratures to use when integrating. Like the OrbitsPerCalculation (get / set), this parameter directly affects the performance of the propagator as well as the accuracy of its results. The drag integration routine is performed by N 9-point Gaussian quadratures per orbit, where N is the number set here. By default, this is set to 6 to ensure accuracy, but can be lowered to improve performance. To determine lifetime, the routine approximately integrates the slowly varying orbit elements over time. It does this by integrating over one orbit to determine the rate-of-change of each variable, and then assumes this rate is constant for N number of OrbitsPerCalculation (get / set). The integration of 1 orbit is done over N sub-arcs when N is the number of quadratures. The sub-arcs are of constant angular measure (in true anomaly, not time). To increase accuracy, make N larger. Each sub-arc is integrated using a 9-point Gaussian quadrature (i.e. there are 9 sample points within each sub-arc). Highly eccentric satellites, which are in higher drag regimes for very short times compared with their period will need to take much higher numbers of gaussian quadratures to ensure that drag is sampled adequately.
  - setNumberOfGaussianQuadratures
```
public final void setNumberOfGaussianQuadratures(int value)
```
    Sets the number of Gaussian quadratures to use when integrating. Like the OrbitsPerCalculation (get / set), this parameter directly affects the performance of the propagator as well as the accuracy of its results. The drag integration routine is performed by N 9-point Gaussian quadratures per orbit, where N is the number set here. By default, this is set to 6 to ensure accuracy, but can be lowered to improve performance. To determine lifetime, the routine approximately integrates the slowly varying orbit elements over time. It does this by integrating over one orbit to determine the rate-of-change of each variable, and then assumes this rate is constant for N number of OrbitsPerCalculation (get / set). The integration of 1 orbit is done over N sub-arcs when N is the number of quadratures. The sub-arcs are of constant angular measure (in true anomaly, not time). To increase accuracy, make N larger. Each sub-arc is integrated using a 9-point Gaussian quadrature (i.e. there are 9 sample points within each sub-arc). Highly eccentric satellites, which are in higher drag regimes for very short times compared with their period will need to take much higher numbers of gaussian quadratures to ensure that drag is sampled adequately.
  - getUseSecondOrderOblatenessCorrection
```
public final boolean getUseSecondOrderOblatenessCorrection()
```
    Gets a value indicating whether to use second order oblateness (J2) correction when propagating the mean orbital elements. By default, this is true.
  - setUseSecondOrderOblatenessCorrection
```
public final void setUseSecondOrderOblatenessCorrection(boolean value)
```
    Sets a value indicating whether to use second order oblateness (J2) correction when propagating the mean orbital elements. By default, this is true.
  - getReflectivityCoefficient
```
public final double getReflectivityCoefficient()
```
    Gets the coefficient of reflectivity for the satellite. A value of zero indicates the satellite is transparent to solar radiation. A value of one indicates the satellite completely absorbs all the solar radiation perfectly. A value of 5/3 means that it is flat and reflects all incoming light diffusely. A value of 2 means that it is flat and reflects all incoming light specularly.
  - setReflectivityCoefficient
```
public final void setReflectivityCoefficient(double value)
```
    Sets the coefficient of reflectivity for the satellite. A value of zero indicates the satellite is transparent to solar radiation. A value of one indicates the satellite completely absorbs all the solar radiation perfectly. A value of 5/3 means that it is flat and reflects all incoming light diffusely. A value of 2 means that it is flat and reflects all incoming light specularly.
  - getReflectiveCrossSectionalArea
```
public final double getReflectiveCrossSectionalArea()
```
    Gets the mean area presented to the illuminating body (the Sun) during propagation, in square meters. This area is often different from the cross section used for drag.
  - setReflectiveCrossSectionalArea
```
public final void setReflectiveCrossSectionalArea(double value)
```
    Sets the mean area presented to the illuminating body (the Sun) during propagation, in square meters. This area is often different from the cross section used for drag.
  - getSatelliteMass
```
public final double getSatelliteMass()
```
    Gets the mass of the satellite, in kilograms.
  - setSatelliteMass
```
public final void setSatelliteMass(double value)
```
    Sets the mass of the satellite, in kilograms.
  - getDragCoefficient
```
public final double getDragCoefficient()
```
    Gets the coefficient of drag associated with the aerodynamic profile of the satellite. The propagator takes into account the ScalarAtmosphericDensity and DragCrossSectionalArea (get / set) and the drag coefficient provides a proportional measure of how much the body is affected by atmospheric drag. This value must not be negative and is usually in the range between 2.0 and 2.2.
  - setDragCoefficient
```
public final void setDragCoefficient(double value)
```
    Sets the coefficient of drag associated with the aerodynamic profile of the satellite. The propagator takes into account the ScalarAtmosphericDensity and DragCrossSectionalArea (get / set) and the drag coefficient provides a proportional measure of how much the body is affected by atmospheric drag. This value must not be negative and is usually in the range between 2.0 and 2.2.
  - getDragCrossSectionalArea
```
public final double getDragCrossSectionalArea()
```
    Gets the mean area of the satellite which is presented perpendicular to the relative velocity of the atmosphere and produces drag. The area is measured in square meters and is often different from the area used for reflectivity.
  - setDragCrossSectionalArea
```
public final void setDragCrossSectionalArea(double value)
```
    Sets the mean area of the satellite which is presented perpendicular to the relative velocity of the atmosphere and produces drag. The area is measured in square meters and is often different from the area used for reflectivity.
  - getUseRotatingAtmosphere
```
public final boolean getUseRotatingAtmosphere()
```
    Gets a value indicating whether to model the atmosphere as rotating rather than static. This models the west-to-east winds induced by atmospheric rotation over the Earth. By default, this is false.
  - setUseRotatingAtmosphere
```
public final void setUseRotatingAtmosphere(boolean value)
```
    Sets a value indicating whether to model the atmosphere as rotating rather than static. This models the west-to-east winds induced by atmospheric rotation over the Earth. By default, this is false.
  - getDecayAltitude
```
public final double getDecayAltitude()
```
    Gets the altitude to use to determine when a satellite will permanently decay. This is the point at which the orbit has decayed and calculations stop. By default, this is 65,000 meters.
  - setDecayAltitude
```
public final void setDecayAltitude(double value)
```
    Sets the altitude to use to determine when a satellite will permanently decay. This is the point at which the orbit has decayed and calculations stop. By default, this is 65,000 meters.
  - getInitialEpoch
```
@Nonnull
public final JulianDate getInitialEpoch()
```
    Gets the time at which the InitialConditions (get / set) are valid.
  - setInitialEpoch
```
public final void setInitialEpoch(@Nonnull
                                  JulianDate value)
```
    Sets the time at which the InitialConditions (get / set) are valid.
  - computeLifetime
```
public final OrbitLifetimeResults computeLifetime()
```
    Compute the set of metrics describing the time history of the orbit as well as the number of orbit revolutions and the time at which the orbit is expected to decay. Note that if the propagation reaches the OrbitCountLimit (get / set) or DurationLimit (get / set) the results will not represent a decayed orbit. This can also happen if there is a problem with the initial state or something else went wrong during propagation. Check the Status (get / set) in order to determine whether the calculation completed successfully.
    
    Returns:
    
    The results containing the decay date and orbit history.
  - computeLifetime
```
public final OrbitLifetimeResults computeLifetime(ITrackCalculationProgress progress)
```
    Compute the set of metrics describing the time history of the orbit as well as the number of orbit revolutions and the time at which the orbit is expected to decay. Note that if the propagation reaches the OrbitCountLimit (get / set) or DurationLimit (get / set) the results will not represent a decayed orbit. This can also happen if there is a problem with the initial state or something else went wrong during propagation. Check the Status (get / set) in order to determine whether the calculation completed successfully.
    
    Parameters:
    
    progress - A progress tracker that can support reporting progress during calculation as well as cancellation.
    
    Returns:
    
    The results containing the decay date and orbit history.

Class LifetimeOrbitPropagator

Constructor Summary

Method Summary

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

Methods inherited from class java.lang.Object

Constructor Detail

Method Detail

clone

checkForSameDefinition

computeCurrentDefinitionHashCode

enumerateDependencies

getCentralBody

setCentralBody

getAtmosphericDensity

setAtmosphericDensity

getOrbitLimitType

setOrbitLimitType

getInitialConditions

setInitialConditions

getOrbitCountLimit

setOrbitCountLimit

getDurationLimit

setDurationLimit

getOrbitsPerCalculation

setOrbitsPerCalculation

getNumberOfGaussianQuadratures

setNumberOfGaussianQuadratures

getUseSecondOrderOblatenessCorrection

setUseSecondOrderOblatenessCorrection

getReflectivityCoefficient

setReflectivityCoefficient

getReflectiveCrossSectionalArea

setReflectiveCrossSectionalArea

getSatelliteMass

setSatelliteMass

getDragCoefficient

setDragCoefficient

getDragCrossSectionalArea

setDragCrossSectionalArea

getUseRotatingAtmosphere

setUseRotatingAtmosphere

getDecayAltitude

setDecayAltitude

getInitialEpoch

setInitialEpoch

computeLifetime

computeLifetime