agi.foundation.propagators

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

Class SimpleAscentPropagator

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.propagators.CartesianOnePointPropagator

agi.foundation.propagators.SimpleAscentPropagator

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

public final class SimpleAscentPropagator
extends CartesianOnePointPropagator

Propagates a simple (point) launch vehicle from a CentralBody (get / set) to a specified burnout motion.

Constructor Summary

Constructors

Constructor and Description
SimpleAscentPropagator() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	addWarningsHandler(EventHandler<SimpleAscentPropagatorWarnings> value) An event that can be used to check for/handle warnings produced during propagation.
protected boolean	checkForSameDefinition(CartesianOnePointPropagator 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.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
SimpleAscentPropagatorAscentType	getAscentType() Gets the interpolation type for the ascent.
JulianDate	getBurnoutEpoch() Gets the time of burnout, at which the launch vehicle will be at BurnoutPosition (get / set).
Cartographic	getBurnoutPosition() Gets the location of burnout.
double	getBurnoutVelocityAzimuth() Gets the burnout velocity's azimuth.
double	getBurnoutVelocityFightPathAngle() Gets the burnout velocity's flight path angle.
SimpleAscentPropagatorBurnoutVelocityFrame	getBurnoutVelocityFrame() Gets which reference frame the burnout velocity is specified in.
double	getBurnoutVelocityMagnitude() Gets the burnout velocity magnitude in the reference frame of the CentralBody (get / set) as indicated by the property BurnoutVelocityFrame (get / set).
CentralBody	getCentralBody() Gets the central body to be used for the launch segment.
MotionEvaluator1<Cartesian>	getEvaluator(EvaluatorGroup group) Gets an evaluator that can propagate at individual dates.
double	getInitialAcceleration() Gets the initial acceleration at launch.
TranslationalMotionInterpolator	getInterpolator() Gets the interpolator used to get values between the analytical points.
JulianDate	getLaunchEpoch() Gets the epoch at which launch occurs.
Cartographic	getLaunchPosition() Gets the position on/near the CentralBody (get / set) where the launch takes place.
protected ReferenceFrame	getMotionReferenceFrame() Gets the reference frame in which the motion is defined.
int	getNumberOfSamplePoints() Gets the number of points to be sampled on the interpolation spline.
int	getOrder() Gets the order of the motion produced by the propagator.
static Motion1<Cartesian>	mixedFixedPositionAndInertialVelocityToMotionFixed(boolean isAtPole, KinematicTransformation inertialToFixed, Cartesian position, double inertialSpeed, double inertialFlightPathAngle, double inertialAzimuth) This method computes the burnout motion in the fixed frame of the CentralBody (get / set) from mixed inertial velocity/fixed position input.
void	removeWarningsHandler(EventHandler<SimpleAscentPropagatorWarnings> value) An event that can be used to check for/handle warnings produced during propagation.
void	setAscentType(SimpleAscentPropagatorAscentType value) Sets the interpolation type for the ascent.
void	setBurnoutEpoch(JulianDate value) Sets the time of burnout, at which the launch vehicle will be at BurnoutPosition (get / set).
void	setBurnoutPosition(Cartographic value) Sets the location of burnout.
void	setBurnoutVelocityAzimuth(double value) Sets the burnout velocity's azimuth.
void	setBurnoutVelocityFightPathAngle(double value) Sets the burnout velocity's flight path angle.
void	setBurnoutVelocityFrame(SimpleAscentPropagatorBurnoutVelocityFrame value) Sets which reference frame the burnout velocity is specified in.
void	setBurnoutVelocityMagnitude(double value) Sets the burnout velocity magnitude in the reference frame of the CentralBody (get / set) as indicated by the property BurnoutVelocityFrame (get / set).
void	setCentralBody(CentralBody value) Sets the central body to be used for the launch segment.
void	setInitialAcceleration(double value) Sets the initial acceleration at launch.
void	setInterpolator(TranslationalMotionInterpolator value) Sets the interpolator used to get values between the analytical points.
void	setLaunchEpoch(JulianDate value) Sets the epoch at which launch occurs.
void	setLaunchPosition(Cartographic value) Sets the position on/near the CentralBody (get / set) where the launch takes place.
void	setNumberOfSamplePoints(int value) Sets the number of points to be sampled on the interpolation spline.
void	setOrder(int value) Sets the order of the motion produced by the propagator.

Methods inherited from class agi.foundation.propagators.CartesianOnePointPropagator

checkForSameDefinition, createPoint, getEvaluator, propagate, propagate

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, freezeAggregatedObjects, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleAscentPropagator

public SimpleAscentPropagator()

Initializes a new instance.

The appropriate properties must be set before this propagator can be used.

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(CartesianOnePointPropagator 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 CartesianOnePointPropagator

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 SimpleAscentPropagator.checkForSameDefinition(agi.foundation.propagators.CartesianOnePointPropagator) method.

Overrides:

computeCurrentDefinitionHashCode in class CartesianOnePointPropagator

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.

addWarningsHandler

public final void addWarningsHandler(EventHandler<SimpleAscentPropagatorWarnings> value)

An event that can be used to check for/handle warnings produced during propagation. If not set, the propagator will throw an IllegalStateException if a warning is encountered. The error text in the exception is the same as the summary documentation for each boolean property in the events arguments class.

removeWarningsHandler

public final void removeWarningsHandler(EventHandler<SimpleAscentPropagatorWarnings> value)

An event that can be used to check for/handle warnings produced during propagation. If not set, the propagator will throw an IllegalStateException if a warning is encountered. The error text in the exception is the same as the summary documentation for each boolean property in the events arguments class.

getInterpolator

public final TranslationalMotionInterpolator getInterpolator()

Gets the interpolator used to get values between the analytical points. This defaults to LagrangePolynomialApproximation and order 7. It is recommended that this property be left as the default.

setInterpolator

public final void setInterpolator(TranslationalMotionInterpolator value)

Sets the interpolator used to get values between the analytical points. This defaults to LagrangePolynomialApproximation and order 7. It is recommended that this property be left as the default.

getCentralBody

public final CentralBody getCentralBody()

Gets the central body to be used for the launch segment.

setCentralBody

public final void setCentralBody(CentralBody value)

Sets the central body to be used for the launch segment.

getNumberOfSamplePoints

public final int getNumberOfSamplePoints()

Gets the number of points to be sampled on the interpolation spline.

STK's Astrogator sets this to a fixed value of 2000.

setNumberOfSamplePoints

public final void setNumberOfSamplePoints(int value)

Sets the number of points to be sampled on the interpolation spline.

STK's Astrogator sets this to a fixed value of 2000.

getBurnoutVelocityFrame

@Nonnull
public final SimpleAscentPropagatorBurnoutVelocityFrame getBurnoutVelocityFrame()

Gets which reference frame the burnout velocity is specified in.

setBurnoutVelocityFrame

public final void setBurnoutVelocityFrame(@Nonnull
                                          SimpleAscentPropagatorBurnoutVelocityFrame value)

Sets which reference frame the burnout velocity is specified in.

getAscentType

@Nonnull
public final SimpleAscentPropagatorAscentType getAscentType()

Gets the interpolation type for the ascent. Use the quartic type when specifying an initial acceleration.

setAscentType

public final void setAscentType(@Nonnull
                                SimpleAscentPropagatorAscentType value)

Sets the interpolation type for the ascent. Use the quartic type when specifying an initial acceleration.

getBurnoutVelocityAzimuth

public final double getBurnoutVelocityAzimuth()

Gets the burnout velocity's azimuth. This defaults to zero.

setBurnoutVelocityAzimuth

public final void setBurnoutVelocityAzimuth(double value)

Sets the burnout velocity's azimuth. This defaults to zero.

getBurnoutVelocityFightPathAngle

public final double getBurnoutVelocityFightPathAngle()

Gets the burnout velocity's flight path angle. This defaults to zero.

setBurnoutVelocityFightPathAngle

public final void setBurnoutVelocityFightPathAngle(double value)

Sets the burnout velocity's flight path angle. This defaults to zero.

getOrder

public final int getOrder()

Gets the order of the motion produced by the propagator. This may be up to jerk (order 3).

setOrder

public final void setOrder(int value)

Sets the order of the motion produced by the propagator. This may be up to jerk (order 3).

getBurnoutVelocityMagnitude

public final double getBurnoutVelocityMagnitude()

Gets the burnout velocity magnitude in the reference frame of the CentralBody (get / set) as indicated by the property BurnoutVelocityFrame (get / set). This defaults to zero m/s.

setBurnoutVelocityMagnitude

public final void setBurnoutVelocityMagnitude(double value)

Sets the burnout velocity magnitude in the reference frame of the CentralBody (get / set) as indicated by the property BurnoutVelocityFrame (get / set). This defaults to zero m/s.

getInitialAcceleration

public final double getInitialAcceleration()

Gets the initial acceleration at launch. The AscentType (get / set) type must be set to quartic to use. This defaults to zero m/s^2.

setInitialAcceleration

public final void setInitialAcceleration(double value)

Sets the initial acceleration at launch. The AscentType (get / set) type must be set to quartic to use. This defaults to zero m/s^2.

getLaunchPosition

@Nonnull
public final Cartographic getLaunchPosition()

Gets the position on/near the CentralBody (get / set) where the launch takes place.

setLaunchPosition

public final void setLaunchPosition(@Nonnull
                                    Cartographic value)

Sets the position on/near the CentralBody (get / set) where the launch takes place.

getLaunchEpoch

@Nonnull
public final JulianDate getLaunchEpoch()

Gets the epoch at which launch occurs.

setLaunchEpoch

public final void setLaunchEpoch(@Nonnull
                                 JulianDate value)

Sets the epoch at which launch occurs.

getBurnoutPosition

@Nonnull
public final Cartographic getBurnoutPosition()

Gets the location of burnout.

setBurnoutPosition

public final void setBurnoutPosition(@Nonnull
                                     Cartographic value)

Sets the location of burnout.

getBurnoutEpoch

@Nonnull
public final JulianDate getBurnoutEpoch()

Gets the time of burnout, at which the launch vehicle will be at BurnoutPosition (get / set).

setBurnoutEpoch

public final void setBurnoutEpoch(@Nonnull
                                  JulianDate value)

Sets the time of burnout, at which the launch vehicle will be at BurnoutPosition (get / set).

mixedFixedPositionAndInertialVelocityToMotionFixed

@Nonnull
public static Motion1<Cartesian> mixedFixedPositionAndInertialVelocityToMotionFixed(boolean isAtPole,
                                                                                              @Nonnull
                                                                                              KinematicTransformation inertialToFixed,
                                                                                              @Nonnull
                                                                                              Cartesian position,
                                                                                              double inertialSpeed,
                                                                                              double inertialFlightPathAngle,
                                                                                              double inertialAzimuth)

This method computes the burnout motion in the fixed frame of the CentralBody (get / set) from mixed inertial velocity/fixed position input.

Parameters:

isAtPole - Indicates whether the position vector is at a pole of the central body ellipsoid.

inertialToFixed - The transformation from the inertial reference frame to the fixed reference frame.

position - The position of the launch vehicle in the CentralBody (get / set)'s fixed frame at burnout time.

inertialSpeed - The speed in the inertial frame.

inertialFlightPathAngle - The flight path angle in the inertial frame.

inertialAzimuth - The angle from North at the burnout position.

Returns:

A Motion1 representing the burnout state in the fixed frame.

getEvaluator

public MotionEvaluator1<Cartesian> getEvaluator(EvaluatorGroup group)

Gets an evaluator that can propagate at individual dates.

This evaluator propagates the orbit state. The result of evaluating will be a Motion1 corresponding to the orbital state at the given JulianDate expressed in the propagator's ReferenceFrame.

Note: when evaluating with this evaluator, it may be more efficient to specify times using an ArithmeticSafeStandard (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.

Specified by:

getEvaluator in class CartesianOnePointPropagator

Parameters:

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

Returns:

The evaluator.

getMotionReferenceFrame

protected ReferenceFrame getMotionReferenceFrame()

Gets the reference frame in which the motion is defined.

Specified by:

getMotionReferenceFrame in class CartesianOnePointPropagator

Returns:

The reference frame.