public class Sgp4Propagator extends CartesianOnePointPropagator
Propagates an orbit using the NORAD SGP4/SDP4 model as defined by the Center for Space Standards and Innovation (CSSI). More information and the algorithm's code can be found at www.centerforspace.com.
Note that the SGP4 propagator performs its propagation using the InternationalAtomicTime (get).
If the user asks for a propagation over an interval and timestep specified in CoordinatedUniversalTime (get),
the system interprets this to mean that the reported values should be in CoordinatedUniversalTime (get).
However, in order to compute the correct timespans (potentially propagating through leap seconds), the system will convert to
InternationalAtomicTime (get) in order to compare times. Since the length of
a second is different in various time standards, the stepsize is measured in the time standard the user specifies even though the
comparisons and propagation occurs in InternationalAtomicTime (get).
If the length of a given time step is important, this may be a necessary calculation.
However, the performance of the SGP4 propagation can be improved by specifying input times in
InternationalAtomicTime (get).
The acceleration returned from the SGP4Propagator is identical to the J4Propagator, which is an approximation used to prevent
code using this propagator from being unable to provide analysis in the absence of acceleration.
In DME Component Libraries, there are a number of places that expect or require acceleration information from propagators.
In order to support this, the Sgp4Propagator will return an acceleration when asked. However, because the SGP4 theory
does not explicitly contain a representation of the acceleration and the velocity of the SGP4 theory does not correspond
exactly with the position, the acceleration returned for SGP4 is an approximation. Compared with numerical differentiation
of the position, the velocity returned from the SGP4 theory can have a discrepancy anywhere from a few millimeters to
several meters. Since the acceleration perturbations from drag and third body effects are several orders of magnitude less
than gravitational effects, the J4 perturbations are used here to approximate the acceleration for SGP4.
The following example shows how to create an Sgp4Propagator from a Two Line Element Set:
String tleString =
"1 20724U 90068A 02173.73395695 -.00000086 00000-0 00000-0 0 1771\n" +
"2 20724 56.1487 21.0845 0183651 226.6216 131.8780 2.00562381 85500\n";
TwoLineElementSet tle = new TwoLineElementSet(tleString);
Sgp4Propagator propagator = new Sgp4Propagator(tle);| Modifier and Type | Class and Description |
|---|---|
static class |
Sgp4Propagator.Sgp4EstimationInput
A class containing configuration information for the static estimation methods available on the
Sgp4Propagator. |
static class |
Sgp4Propagator.Sgp4EstimationOutput
A class containing the estimated
Sgp4Elements along with the associated
information from the fit. |
| Modifier | Constructor and Description |
|---|---|
|
Sgp4Propagator()
Initializes a new instance with default values.
|
|
Sgp4Propagator(Iterable<? extends Sgp4Elements> elementSets)
Constructs a new instance of an
Sgp4Propagator using the specified initial conditions. |
|
Sgp4Propagator(Sgp4Elements initialConditions)
Constructs a new instance of an
Sgp4Propagator using the specified initial conditions. |
protected |
Sgp4Propagator(Sgp4Propagator existingInstance,
CopyContext context)
Initializes a new instance as a copy of an existing instance.
|
| Modifier and Type | Method and Description |
|---|---|
protected boolean |
checkForSameDefinition(CartesianOnePointPropagator other)
Checks to determine if another instance has the same definition as this instance and
returns
true if it does. |
protected boolean |
checkForSameDefinition(Sgp4Propagator 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.
|
PropagatorPoint |
createPoint()
Creates a
Point that represents the motion produced by this propagator. |
void |
enumerateDependencies(DependencyEnumerator enumerator)
Enumerates the dependencies of this object by calling
DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. |
static Sgp4Propagator.Sgp4EstimationOutput |
estimateElements(DateMotionCollection1<Cartesian> ephemerisInTEME,
Cartesian epochPosition,
Cartesian epochVelocity,
Sgp4Propagator.Sgp4EstimationInput configuration)
Produces a batch least squares fit for a given set of trajectory observations (states).
|
static Sgp4Propagator.Sgp4EstimationOutput |
estimateElements(DateMotionCollection1<Cartesian> ephemerisInTEME,
Sgp4Propagator.Sgp4EstimationInput configuration)
Produces a batch least squares fit for a given set of trajectory observations (states).
|
protected void |
freezeAggregatedObjects()
Called by
DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object. |
DefinitionalObjectCollection<Sgp4Elements> |
getElementSets()
Gets the set of elements from which to propagate.
|
MotionEvaluator1<Cartesian> |
getEvaluator(EvaluatorGroup group)
Gets an evaluator that can propagate at individual dates.
|
Sgp4Elements |
getInitialConditions()
Gets the first set of elements in the
ElementSets (get). |
protected ReferenceFrame |
getMotionReferenceFrame()
Gets the reference frame in which the motion is defined.
|
ReferenceFrame |
getReferenceFrame()
Gets True Equator, Mean Equinox (TEME) reference frame, the coordinate system in which SGP4 produces ephemeris.
|
static Sgp4Elements |
meanElementsAtEpoch(JulianDate date,
Cartesian posInTEME,
Cartesian velInTEME)
Produces an element set from a given
Cartesian state at a given time. |
static Sgp4Elements |
meanElementsAtEpoch(JulianDate date,
Cartesian posInTEME,
Cartesian velInTEME,
int maximumIterations)
Produces an element set from a given
Cartesian state at a given time. |
static Sgp4Elements |
meanElementsAtEpoch(JulianDate date,
Cartesian posInTEME,
Cartesian velInTEME,
int maximumIterations,
double bStarValue)
Produces an element set from a given
Cartesian state at a given time. |
void |
setInitialConditions(Sgp4Elements value)
Sets the first set of elements in the
ElementSets (get). |
checkForSameDefinition, getEvaluator, propagate, propagateareSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozenpublic Sgp4Propagator()
public Sgp4Propagator(@Nonnull Sgp4Elements initialConditions)
Sgp4Propagator using the specified initial conditions.initialConditions - The initial conditions from which to propagate.ArgumentNullException - Thrown if initialConditions is null.ArgumentException - Thrown when initialConditions is a TwoLineElementSet with
ephemeris type 4 that is not correctly propagated by Sgp4Propagator.public Sgp4Propagator(@Nonnull Iterable<? extends Sgp4Elements> elementSets)
Sgp4Propagator using the specified initial conditions.elementSets - The initial conditions from which to propagate.ArgumentNullException - Thrown if elementSets is null.ArgumentException - Thrown when elementSets has a TwoLineElementSet with
ephemeris type 4 that is not correctly propagated by Sgp4Propagator.protected Sgp4Propagator(@Nonnull Sgp4Propagator existingInstance, @Nonnull CopyContext context)
See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor
in a derived class.
existingInstance - The existing instance to copy.context - A CopyContext that controls the depth of the copy.ArgumentNullException - Thrown when existingInstance or context is null.public Object clone(CopyContext 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:
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:
CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to
non-evaluators.
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the
same CopyContext passed to the constructor.
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;clone in interface ICloneWithContextclone in class DefinitionalObjectcontext - The context to use to perform the copy.protected final boolean checkForSameDefinition(CartesianOnePointPropagator other)
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).checkForSameDefinition in class CartesianOnePointPropagatorother - The other instance to compare to this one.true if the two objects are defined equivalently; otherwise false.protected boolean checkForSameDefinition(Sgp4Propagator other)
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).other - The other instance to compare to this one.true if the two objects are defined equivalently; otherwise false.protected int computeCurrentDefinitionHashCode()
Sgp4Propagator.checkForSameDefinition(agi.foundation.propagators.CartesianOnePointPropagator) method.computeCurrentDefinitionHashCode in class CartesianOnePointPropagatorpublic void enumerateDependencies(DependencyEnumerator enumerator)
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.enumerateDependencies in interface IEnumerateDependenciesenumerateDependencies in class DefinitionalObjectenumerator - The enumerator that is informed of the dependencies of this object.protected void freezeAggregatedObjects()
DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object.
Derived classes which contain additional aggregated objects MUST override this method, call the base
implementation, and freeze aggregated objects introduced by the derived class. The objects that need to be
frozen in this method are frequently created in this object's constructor and are not settable via
properties.freezeAggregatedObjects in class DefinitionalObjectpublic final Sgp4Elements getInitialConditions()
ElementSets (get).public final void setInitialConditions(Sgp4Elements value)
ElementSets (get).ArgumentNullException - Thrown when value is null.ArgumentException - Thrown when value is a TwoLineElementSet with
ephemeris type 4 that is not correctly propagated by Sgp4Propagator.@Nonnull public final DefinitionalObjectCollection<Sgp4Elements> getElementSets()
@Nonnull public final ReferenceFrame getReferenceFrame()
The TEME frame is obtained from the TrueEquatorMeanEquinoxFrame (get / set) property
of the EarthCentralBody that is stored in the CentralBodiesFacet instance in
the CalculationContext.
@Nonnull public static Sgp4Elements meanElementsAtEpoch(@Nonnull JulianDate date, @Nonnull Cartesian posInTEME, @Nonnull Cartesian velInTEME)
Cartesian state at a given time. Since SGP4 uses
perturbations, the classical orbital elements produced by ModifiedKeplerianElements may
not correspond to the specified position and velocity when propagated as SGP4 elements. This method
performs a simple iteration to correct the classical elements so that the resulting SGP4 elements will
represent the specified position and velocity at the given time as accurately as possible. This will
assume that the BStar (get / set) value is zero.@Nonnull public static Sgp4Elements meanElementsAtEpoch(@Nonnull JulianDate date, @Nonnull Cartesian posInTEME, @Nonnull Cartesian velInTEME, int maximumIterations)
Cartesian state at a given time. Since SGP4 uses
perturbations, the classical orbital elements produced by ModifiedKeplerianElements may
not correspond to the specified position and velocity when propagated as SGP4 elements. This method
performs a simple iteration to correct the classical elements so that the resulting SGP4 elements will
represent the specified position and velocity at the given time as accurately as possible. This will
assume that the BStar (get / set) value is zero.date - The epoch of the state.posInTEME - The position in the TrueEquatorMeanEquinoxFrame (get / set).velInTEME - The velocity in the TrueEquatorMeanEquinoxFrame (get / set).maximumIterations - The maximum number of iterations to perform when trying to match the specified state.@Nonnull public static Sgp4Elements meanElementsAtEpoch(@Nonnull JulianDate date, @Nonnull Cartesian posInTEME, @Nonnull Cartesian velInTEME, int maximumIterations, double bStarValue)
Cartesian state at a given time. Since SGP4 uses
perturbations, the classical orbital elements produced by ModifiedKeplerianElements may
not correspond to the specified position and velocity when propagated as SGP4 elements. This method
performs a simple iteration to correct the classical elements so that the resulting SGP4 elements will
represent the specified position and velocity at the given time as accurately as possible. This will
use the specified value for BStar (get / set) in the resulting element set. Also,
note that this method may have difficulty converging for perfectly circular orbits.date - The epoch of the state.posInTEME - The position in the TrueEquatorMeanEquinoxFrame (get / set).velInTEME - The velocity in the TrueEquatorMeanEquinoxFrame (get / set).maximumIterations - The maximum number of iterations to perform when trying to match the specified state.bStarValue - Specifies the value of BStar (get / set) to use when producing the
set of SGP4 elements which match the given state.@Nonnull public static Sgp4Propagator.Sgp4EstimationOutput estimateElements(@Nonnull DateMotionCollection1<Cartesian> ephemerisInTEME, @Nonnull Sgp4Propagator.Sgp4EstimationInput configuration)
RequestedEstimationEpoch (get / set)
in the ephemerisInTEME and use the Sgp4Propagator.meanElementsAtEpoch(JulianDate,Cartesian,Cartesian) to
produce an initial guess.ephemerisInTEME - The set of time indexed state observations over which to perform the fit.configuration - Additional configuration data indicating how to perform the fit and whether to solve for
the BSTAR drag term. This can also prescribe a value for BSTAR to use when estimating the elements.Sgp4Elements and associated information from the fit.@Nonnull public static Sgp4Propagator.Sgp4EstimationOutput estimateElements(@Nonnull DateMotionCollection1<Cartesian> ephemerisInTEME, @Nonnull Cartesian epochPosition, @Nonnull Cartesian epochVelocity, @Nonnull Sgp4Propagator.Sgp4EstimationInput configuration)
RequestedEstimationEpoch (get / set) in the configuration.
The estimation takes this state and uses Sgp4Propagator.meanElementsAtEpoch(JulianDate,Cartesian,Cartesian) to
produce an initial guess for the least squares.ephemerisInTEME - The set of time indexed state observations over which to perform the fit.epochPosition - The position at the RequestedEstimationEpoch (get / set) in the
TrueEquatorMeanEquinoxFrame (get / set) frame.epochVelocity - The velocity at the RequestedEstimationEpoch (get / set) in the
TrueEquatorMeanEquinoxFrame (get / set) frame.configuration - Additional configuration data indicating how to perform the fit and whether to solve for
the BSTAR drag term. This can also prescribe a value for BSTAR to use when estimating the elements.Sgp4Elements and associated information from the fit.protected ReferenceFrame getMotionReferenceFrame()
getMotionReferenceFrame in class CartesianOnePointPropagatorpublic PropagatorPoint createPoint()
Point that represents the motion produced by this propagator.createPoint in class CartesianOnePointPropagatorpublic MotionEvaluator1<Cartesian> getEvaluator(EvaluatorGroup group)
Gets an evaluator that can propagate at individual dates.
This evaluator propagates the orbit state from InitialConditions (get / set)
around the Earth. The result of evaluating
will be the Motion<Cartesian> corresponding to the orbital
position and velocity at the given JulianDate expressed in the EarthCentralBody's
TrueEquatorMeanEquinoxFrame (get / set).
Note* When evaluating with this evaluator, it will be more efficient to specify times using
the InternationalAtomicTime (get) to avoid the need
to convert in order to perform the propagation. The length of a time step may be different in
different TimeStandards. So be careful when specifying times.
getEvaluator in class CartesianOnePointPropagatorgroup - The group with which to associate the new evaluator. By grouping evaluators
that are often evaluated at the same Julian dates, common computations can be performed only once
for the entire group instead of multiple times for each evaluator.ArgumentNullException - Thrown when the group is null.CartesianOnePointPropagator.createPoint()